docs: 全面更新 README.md + ARCHITECTURE.md v3.0

ARCHITECTURE.md v3.0: 护城河分析,容器拓扑,技术栈矩阵,功能架构,双Claw单引擎,模型同步,安全纵深,qihu-design-system,迭代路线. README.md v3.0: 快速开始,核心能力,架构总览,项目结构,开发指南,平台数据.
2026-08-12 09:20:55 +08:00
1 parent 54b444b651
commit d2d133f22a
@@ -0,0 +1,416 @@
 # 七虎AI PaaS 平台 — 架构设计与实施方案 v3.0
 > **最后更新**: 2026-08-12
 > **版本**: v3.0
 > **用途**: 平台竞争力、护城河、技术框架、功能架构、业务逻辑完整文档
 > **维护**: 随系统迭代实时更新
 > **仓库**: http://git.qihuyun.com/qyyfw/qihuaiflow
 ---
 ## 一、平台护城河 (Moat)
 ### 1.1 核心竞争壁垒
 | 壁垒维度 | 具体实现 | 竞争门槛 |
 |---------|---------|---------|
 | **模型聚合网关** | LiteLLM + STORE_MODEL_IN_DB，4+ 厂商统一 OpenAI 协议，管理员 UI 一键增删模型自动同步 | 竞品需手动配置模型路由，无 admin UI 驱动 |
 | **双 Claw 单引擎** | Web SSE + IM Bot (微信) 共享 `EngineCore._send_message_core`，能力发现、MCP 调用、LLM 路由只实现一次 | 竞品 Web/IM 两套代码，同步成本高 |
 | **技能市场闭环** | Skills 发现-安装-搜索(Meilisearch)-执行全生命周期，支持 97+ 技能、14 类 capability | 需自建市场 + 搜索引擎 + 沙箱执行 |
 | **ngnix 安全纵深** | 四层防护: 限流(API 30r/s/Admin 5r/s/Login 1r/s) + 扫描器拦截(14类path/20类UA) + 自动IP黑名单(5min cron/24h TTL) + SSL终止 | 竞品大多只做限流 |
 | **模型双轨制已消除** | #965 平台→LiteLLM REST API 同步，管理员 UI 操作即生效，不再 SSH 手动改 yaml | 多数平台仍手动配置网关 |
 | **设计语言系统** | 完整 `qihu-design-system` (53 modules, CSS 55KB, 品牌色 #5B5FED + 渐变 + 玻璃/辉光 + 暗态) | 需专业设计师 + 前端团队长期维护 |
 | **可观测性** | Prometheus+Grafana+Alloy OTel 双 Claw 标签看板 + 日志审计 | 中小企业平台通常缺监控 |
 ### 1.2 竞争策略
 | 策略 | 我方 | 竞品(AI PaaS) | 竞品(垂直SaaS) |
 |------|------|-------------|-------------|
 | 模型数量 | 14+ 实时可增删 | 3-5 个 | 1 个 |
 | 技能市场 | 97 个，自建生态 | 0-20 个 | 无 |
 | IM Bot | 微信 + 企业微信扩展 | 无 | 自己开发 |
 | 多租户 | PG RLS 行级安全 | 应用层隔离 | 单租户 |
 | 部署 | Docker Compose 一行启动 | Kubernetes 复杂 | 无 Docker |
 | 定价 | 免费层 + 会员订阅 | 仅付费 | 固定价 |
 ---
 ## 二、部署架构
 ### 2.1 物理拓扑
 ```
                    Internet
                        │
              ┌─────────▼─────────┐
              │ 宝塔 Nginx :443    │ SSL 终止 + 反向代理
              │ root: /www/dk_    │
              │  project/wwwroot/  │
              │  ai.qihuyun.com   │
              └─────────┬─────────┘
                        │ :12888
         ┌──────────────┼──────────────┐
         │              │              │
    ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐
    │ Nginx    │  │ uvicorn  │  │ 静态资源 │
    │ :8080    │  │ :18080   │  │ dist/    │
    │ proxy_pass  │ FastAPI  │  │ React SPA│
    └──────────┘  └────┬─────┘  └──────────┘
                       │
         ┌─────────────┼─────────────────┐
         │             │                 │
    ┌────▼────┐   ┌───▼────┐       ┌────▼─────┐
    │Postgres │   │ Redis  │       │LiteLLM   │
    │PG18     │   │ :6379  │       │ :4000    │
    │+pgvector│   └────────┘       │ LLM 网关 │
    └─────────┘                    └──────────┘
 ```
 ### 2.2 容器清单 (Docker Compose)
 | 容器 | 镜像 | 端口 | 用途 |
 |------|------|------|------|
 | **qihu-aiflow** | qihuaiflow:with-deps | 12888/18080/8080 | 主应用: Nginx + FastAPI + React dist |
 | **qihu-aiflow-litellm** | berriai/litellm:main-stable | 14000→4000 | LLM 网关 + DB 模式模型管理 |
 | **qihu-aiflow-pg18** | pgvector/pgvector:pg16 | 5432 | PostgreSQL 主库 + 向量引擎 |
 | **qihu-aiflow-redis** | redis:7-alpine | 6379 | 缓存/队列/会话 |
 | **qihu-aiflow-casdoor** | casdoor | 8000 | 统一认证 OAuth2/OIDC |
 | **qihu-aiflow-meilisearch** | meilisearch:v1.11 | 17700 | 技能市场搜索引擎 |
 | **qihu-aiflow-prometheus** | prom/prometheus | 9090 | 指标采集 |
 | **qihu-aiflow-grafana** | grafana/grafana | 3000 | 可视化看板 |
 | **qihu-aiflow-alloy** | grafana/alloy | - | 日志采集 Agent |
 | **qihu-aiflow-node-exporter** | prom/node-exporter | 9100 | 宿主机指标 |
 ### 2.3 网络与域名
 | 域名 | 用途 |
 |------|------|
 | ai.qihuyun.com | 主站 (React SPA + FastAPI API) |
 | docs.qihuyun.com | 文档站 |
 | bot.qihuyun.com | Bot 回调地址 |
 ---
 ## 三、技术栈矩阵
 | 层级 | 技术 | 版本 | 选型理由 |
 |------|------|------|---------|
 | **后端框架** | FastAPI (Python 3.11) | 0.115+ | 异步原生、SSE 流式、Pydantic 验证、自动 OpenAPI |
 | **ASGI 服务器** | uvicorn | 0.30+ | 单进程事件循环、生产级 |
 | **前端框架** | React + Vite | 18.3 + 5.4 | 组件化、HMR、TypeScript 5.6 严格模式 |
 | **前端构建** | Tailwind CSS v4.3 | @tailwindcss/vite | utility-first, design token 驱动 |
 | **状态管理** | Zustand 5 | persist | 轻量级，三态主题 (light/dark/system) |
 | **关系数据库** | PostgreSQL 18 | pgvector 0.8.4 | JSONB、向量原生命支持 |
 | **向量引擎** | pgvector | 0.8.4 | 与主库同集群、混合检索 BM25+语义 |
 | **缓存/队列** | Redis 7 | - | 会话、工具列表缓存、事件总线 |
 | **认证** | Casdoor | latest | OAuth2/OIDC、自建身份提供商 |
 | **ORM** | SQLAlchemy 2.0 | 2.0.36 | 成熟生态、async 支持、psycopg |
 | **LLM 客户端** | openai Python SDK | 1.x | 统一 OpenAI 协议接入 |
 | **LLM 网关** | LiteLLM | main-stable | 模型路由、协议转换、费用追踪、key 管理 |
 | **MCP 客户端** | mcp Python SDK | 0.28.1 | Anthropic 官方 SDK、streamable_http/SSE |
 | **搜索引擎** | Meilisearch | v1.11 | BM25 + jieba 中文分词、sub-50ms 响应 |
 | **代理** | Nginx | 1.25+ | 反向代理、静态文件、SSL、限流、扫描器拦截 |
 | **可观测** | Prometheus + Grafana | latest | 指标仪表盘、双 Claw OTel 标签 |
 | **容器** | Docker Compose | v2 | 单机部署、一行启动 |
 ---
 ## 四、功能架构
 ### 4.1 系统分层
 ```
 ┌─────────────────────────────────────────────────┐
 │                  表现层 (Frontend)                │
 │  React SPA | Tailwind CSS | Zustand State        │
 │  AppShell (NavRail+抽屉) | 三态主题              │
 ├─────────────────────────────────────────────────┤
 │                  网关层 (Gateway)                 │
 │  Nginx | SSL 终止 | 限流 | 扫描器拦截 | IP 黑名单 │
 ├─────────────────────────────────────────────────┤
 │                  API 层 (FastAPI)                 │
 │  auth | chat | admin | market | agents | mcp     │
 │  skills | storage | billing | im_llm            │
 ├─────────────────────────────────────────────────┤
 │                业务逻辑层 (Core)                  │
 │  EngineCore | LLM Router | Node Registry         │
 │  Claw Adapters (SSE/Buffer) | OTel               │
 ├─────────────────────────────────────────────────┤
 │                 协议网关层                        │
 │  LiteLLM (model routing) | MCP Protocol         │
 ├─────────────────────────────────────────────────┤
 │                 数据层 (Storage)                  │
 │  PostgreSQL+pgvector | Redis | Meilisearch       │
 │  Qiniu/OSS Object Storage | Casdoor OAuth       │
 └─────────────────────────────────────────────────┘
 ```
 ### 4.2 核心功能模块
 #### 前台 (Frontend Pages)
 | 模块 | 路径 | 功能 |
 |------|------|------|
 | 落地页 | `/` | 平台介绍 + Hero + 能力展示 |
 | AI 对话 | `/chat` | SSE 流式对话、代码块渲染、Markdown、媒体预览 |
 | 知识库 | `/knowledge` | 文档上传、RAG 检索、向量索引管理 |
 | 技能市场 | `/market` | Meilisearch 搜索、技能安装、上架审核 |
 | Token 驾驶舱 | `/token` | 实时用量、消耗趋势、预警告警 |
 | 会员/定价 | `/pricing` | 套餐对比、微信支付订阅、增值付费 |
 | 个人中心 | `/profile` | 用户信息、主题设置、API Key 管理 |
 | 通知中心 | `/notifications` | 系统消息、订单通知、告警 |
 | Agent 画布 | `/agent` | 可视化编排、DAG 工作流编辑 |
 | App 服务 | `/apps` | 第三方应用集成(小说、视频等) |
 #### 后台 (Admin Pages)
 | 模块 | 路径 | 功能 |
 |------|------|------|
 | 平台驾驶舱 | `/admin` | 用户数/模型数/调用量/营收概览 |
 | 大模型库 | `/admin/models` | 供应商管理、模型 CRUD、连接测试、能力默认值配置、**自动同步 LiteLLM** |
 | Agent 管理 | `/admin/agents` | Agent 创建/编辑/状态 |
 | 技能管理 | `/admin/skills` | 技能审批、上架/下架、分类 |
 | MCP 管理 | `/admin/mcp` | MCP Server 注册/授权 |
 | 用户管理 | `/admin/users` | 用户 CRUD、角色分配 |
 | 会员管理 | `/admin/membership` | 套餐配置、续费管理 |
 | 推广系统 | `/admin/promotion` | 邀请链接、佣金结算 |
 | 计费管理 | `/admin/billing` | 充值记录、订单、退款 |
 | 应用市场 | `/admin/market` | 应用审核、产品定价、webhook |
 | 系统设置 | `/admin/settings` | 站点配置、SMS、存储 |
 | 日志审计 | `/admin/logs` | 操作日志、不可删除 |
 | Wechat Bot | `/admin/imbots` | 微信连接状态、消息历史 |
 ### 4.3 模型能力体系
 | 能力分类 | 英文标识 | 代表模型 | 用途 |
 |---------|---------|---------|------|
 | 文本对话 | text | DeepSeek-V4-Flash, MiMo-v2.5 | 通用聊天、文档生成 |
 | 推理思考 | thinking | MiMo-v2.5 | 复杂推理、逻辑分析 |
 | 视觉理解 | vision | MiMo-v2.5 | 图片识别、OCR |
 | 工具调用 | tool | MiMo-v2.5 | Function Calling |
 | 图像生成 | image | AGNES-Image-2.0-Flash | AI 绘图 |
 | 视频生成 | video | AGNES-Video-v2.0 | AI 视频生成 |
 | 语音合成 | audio | MOSS-TTSD | TTS 文字转语音 |
 | 语音识别 | asr | TeleSpeechASR | 语音转文字 |
 | OCR 识别 | ocr | DeepSeek-OCR | 文档 OCR |
 | 嵌入向量 | embedding | BAAI/bge-m3 | 文本向量化 |
 | 重排序 | rerank | BAAI/bge-reranker-v2-m3 | 检索结果重排 |
 ---
 ## 五、核心业务逻辑
 ### 5.1 AI 对话处理流 (chat.py)
 ```
 用户消息 → chat.py _send_message_core
  → capability_discovery (发现可用 MCP/Skills/Models)
  → System Prompt 组装 (知识库 + 能力清单 + 对话历史)
  → LiteLLM /v1/chat/completions (master key 认证)
  → SSE 流式返回 → BufferAdapter 缓冲 → SseAdapter 推送
  → 图片生成: AGNES API → async thread → media relay → 微信推送
  → 日志: Token 用量 + 审计
 ```
 ### 5.2 双 Claw 单引擎架构 (Dual Claw)
 ```
 Web Claw (SSE)                 IM Bot Claw (微信)
      │                              │
      ▼                              ▼
 SseAdapter                      BufferAdapter
      │                              │
      └──────────┬───────────────────┘
                 ▼
        EngineCore._send_message_core (唯一引擎)
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
  LLM Router  MCP SDK  Capability Discovery
 ```
 **关键设计原则**:
 - 能力发现 `capability_discovery.py` Web/IM 共用
 - MCP 命名 `mcp__{safe(name,30)}__{safe(tool,50)}__{idx}` 统一
 - `tests/test_dual_claw.py` R-DUAL 集成哨兵
 ### 5.3 模型同步机制 (#965 LiteLLM Sync)
 ```
 管理员 UI "添加模型" → models.py create_model()
  → PostgreSQL aiflow.AIModel 写入 ✅
  → threading.Thread → LiteLLM REST API /model/new ✅
  → LiteLLM litellm DB 热加载 ✅
  → 用户立即可用 ✅
 STORE_MODEL_IN_DB=True (docker-compose)
 ```
 ### 5.4 媒体生成与中转 (#967 media_relay)
 ```
 用户请求 "生成图片" → chat.py 检测 intent
  → AGNES API /v1/images/generations
  → SiliconFlow S3 存储 → 临时 URL (24h)
  → media/relay (httpx stream + domain whitelist)
  → WeChat / Web SSE 内联渲染
 ```
 ### 5.5 安全纵深防御
 ```
 第一层: Nginx 限流
  - API: 30 r/s | Admin: 5 r/s | Login: 1 r/s
 第二层: 扫描器拦截
  - Path 14 类 (.git/.env/wp-login/etc) → 444
  - UA 20 类 (zgrab/nmap/gobuster/etc) → 444
  - Client SDK (curl/wget/python-requests) → 444
 第三层: 自动黑名单
  - /app/backend/nginx/block_ip.py
  - 5min cron + 24h TTL
  - 基于 4xx 错误率和 UA 模式
 第四层: JWT + Casdoor 认证
  - JWT Bearer Token
  - role-based 路由 (super_admin/admin/user)
 ```
 ---
 ## 六、设计系统 (qihu-design-system)
 ### 6.1 设计理念
 **温暖科技感 + 极简主义** (Warm Tech Minimalism)。护眼雾白底，靛蓝 `#5B5FED` 为唯一品牌色。
 ### 6.2 技术实现
 | 维度 | 值 |
 |------|-----|
 | 主品牌色 | `#5B5FED` (indigo) |
 | 暗态品牌色 | `#8289F5` |
 | 签名渐变 | indigo → violet(#8B5CF6) → fuchsia(#D946EF) |
 | 字体 | Inter (正文/标题) + JetBrains Mono (代码) |
 | CSS 框架 | Tailwind v4.3 (@tailwindcss/vite) |
 | 主题 | light / dark / system 三态，Zustand persist + matchMedia |
 | 组件库 | 53 modules，CSS 55KB / JS 244KB / 1.36s build |
 ### 6.3 组件体系
 ```yaml
 ui: Button(6 variants) | Badge(6v) | Input | Card(6v+cardSurface)
 canvas: GenUiCard(7 themes) | StatusRing(6 states) | ChatComposer(glass)
 layout: AppShell(NavRail+drawer+skip-link) | ThemeToggle | ReaderTabs
 ```
 ### 6.4 设计铁律
 - ❌ 禁硬编码 `bg-blue-*`/`bg-sky-*`/`bg-indigo-600`
 - ✅ GenUi 走 primary 语义 token
 - ✅ 变体映射必须 `Record<Variant, string>` + `cn()`，禁 `bg-primary-${w}`
 - ✅ 暗态 `.dark` 双写；玻璃/辉光统一 `.glass`/`.glow`
 - ✅ 动效尊重 `prefers-reduced-motion`
 - ✅ 条纹: `--chat-accent` / `--r-sm|md|lg` / `--chat-ease cubic-bezier(0.2,0.8,0.2,1)` / `--chat-duration 200ms`
 ---
 ## 七、运维与可靠性
 ### 7.1 Safe-Align 工作流
 ```
 ① 备份: docker commit → backup 镜像 + git tag + bundle + PG dump
 ② 拷贝: 仅 git-tracked 源文件 容器→宿主 git
 ③ 提交: git add + commit (不 push)
 ④ 校验: docker restart + 验证 + docker commit → with-deps
 ```
 **真相源**: 容器 (image := container := git)
 ### 7.2 监控
 - Grafana 双 Claw 对比看板 `uid: qihuaiflow-dual-claw-876`
 - OTel traces + metrics (alloy → Prometheus)
 - 日志级别: INFO (生产) / DEBUG (开发)
 ### 7.3 备份策略
 - 每 6h 自动备份 (cron)
 - PG dump (不用 --ssl=0 否则 0 bytes)
 - Docker image snapshot: `qihuaiflow:backup-*{TS}`
 - nginx logrotate 每日轮转
 ---
 ## 八、迭代路线
 ### 8.1 已完成 (2026-08-11)
 | 编号 | 描述 | commit |
 |------|------|--------|
 | #957 | Nginx server 级 root 修复 | 53bbbf3 |
 | #959 | Index.html no-store cache | 45b6939 |
 | #961 | React hydration error fix | 4cf910e |
 | #962 | Global ErrorBoundary | 420e0f6 |
 | #963 | safeLazy chunk load fallback | 679f23f |
 | #964 | React hooks rules fix (#321) | fa38d2c |
 | #965 | LiteLLM platform-model sync | fd84fec |
 | #966 | Container restart loop fix | 75be24c |
 | #967 | media_relay endpoint impl | 54b444b |
 ### 8.2 下一步候选
 | 优先级 | 项目 | 工作量 |
 |--------|------|--------|
 | 🟢 P0 | 企业微信官方 Bot API 接入 | 3 天 |
 | 🟢 P1 | 后端核心模块单测补全 (165→300+) | 3 天 |
 | 🟡 P1 | Alloy traces 配置 bake to image | 1 天 |
 | 🟡 P1 | 多租户 PG RLS 隔离 | 5 天 |
 | ⚪ P2 | 语音/视频流式响应 | 5 天 |
 | ⚪ P2 | Agent 画布可视化编排 | 7 天 |
 ### 8.3 长期方向
 1. **模型 → 智能体**: 从简单的模型调用升级到自主 Agent + 多步推理
 2. **单机 → 集群**: Docker Compose → Kubernetes + Helm
 3. **中国市场 → 国际化**: 多语言 + 多区域部署
 4. **技能市场 → 开放生态**: 第三方开发者平台 + 收入分成
 5. **个人微信 → 企业微信**: 合规化 IM Bot 渠道
 ---
 ## 九、附录
 ### 9.1 服务器信息
 | 项 | 值 |
 |------|-----|
 | IP | 210.16.161.218 |
 | OS | Ubuntu 24.04 |
 | 公网地址 | https://ai.qihuyun.com |
 | 后台地址 | https://ai.qihuyun.com/admin |
 | 默认账户 | admin / admin123 |
 | Git | http://git.qihuyun.com/qyyfw/qihuaiflow |
 ### 9.2 关键文件路径
 | 文件 | 容器路径 |
 |------|---------|
 | 后端入口 | `/app/backend/python/main.py` |
 | AI 对话 | `/app/backend/python/app/api/chat.py` |
 | LLM 网关 | `/app/backend/python/app/core/llm_router.py` |
 | 双 Claw | `/app/backend/python/app/core/claw_adapters.py` |
 | 同步服务 | `/app/backend/python/app/core/litellm_sync.py` |
 | 前端入口 | `/app/frontend/src/main.tsx` |
 | Nginx 配置 | `/etc/nginx/conf.d/aiflow.conf` |
 | LiteLLM 配置 | `/app/config.yaml` (litellm 容器) |
 ### 9.3 调试经验
 | 问题 | 解决方案 |
 |------|---------|
 | 容器重启循环 | docker stop → docker cp 修复文件 → docker start |
 | React #321 hooks error | useState 必须在组件函数内，不能模块顶层 |
 | Chrome 缓存旧 HTML | index.html 加 Cache-Control: no-store |
 | nginx 调测 444 | curl 用 -A 'Mozilla/5.0' 避免被 P1-2 拦截 |
 | Docker tag 短ID 报错 | 必须用完整 sha256: 格式 ID |
 | SSH paramiko 掉线 | get_ssh() 3次重试 + 指数退避 |
@@ -1,546 +1,217 @@
-# Qihu-AIFlow 智能自动化PaaS平台
+# 七虎AI — 智能自动化 PaaS 平台
-## 项目概述
+> **私有化部署 | 零代码 AI SOP | 多模型聚合 | 技能市场 | IM Bot**
-Qihu-AIFlow 是一套**私有化部署、面向个人及小微企业的AI自动化SOP一站式PaaS平台**。用户无需编码即可落地全流程AI自动化业务，平台提供AI对话、知识管理、技能市场、Token计费、会员订阅等完整闭环体验。
+**版本**: v3.0 | **构建日期**: 2026-08-12 | **公网**: https://ai.qihuyun.com | **后台**: `admin / admin123`
 **版本**: v2.0.1  
 **构建日期**: 2026-06-02  
 **仓库地址**: http://git.qihuyun.com/qyyfw/qihuaiflow
 ---
-## 技术环境
+## 🚀 快速开始
 ### 技术栈
 | 层级 | 技术 | 说明 |
 |------|------|------|
 | 前端框架 | React 18 + TypeScript | 现代化响应式UI，HashRouter前端路由 |
 | 构建工具 | Vite 5 | 快速HMR开发服务器，高效生产构建 |
 | UI样式 | CSS Modules | 组件级样式隔离 |
 | 后端框架 | Python 3.11 + FastAPI | 高性能异步Web框架，自动生成OpenAPI文档 |
 | ORM | SQLAlchemy 2.0 | 全功能Python ORM，支持MySQL方言 |
 | 数据库 | MySQL 8.0 | 关系型数据库，InnoDB引擎，utf8mb4编码 |
 | 缓存 | Redis 7 | 内存缓存，支持持久化(AOF)，事件总线 |
 | Web服务器 | Nginx | 反向代理 + 静态资源服务 |
 | 容器化 | Docker + Docker Compose | 一键构建部署，环境隔离 |
 | API认证 | JWT (python-jose) | 无状态Bearer Token认证 |
 | 密码加密 | bcrypt | 安全的密码哈希存储 |
 | 实时通信 | SSE (Server-Sent Events) | AI对话流式输出 |
 | IM平台接入 | 平台适配器模式 | 飞书/微信/钉钉/WhatsApp/Telegram/Slack统一抽象 |
 | 微信集成 | ClawBot API | 微信个人号扫码绑定，官方API对接 |
 ### 核心组件
 | 组件 | 版本 | 用途 |
 |------|------|------|
 | MySQL | 8.0 | 用户数据、聊天记录、知识库、订单、配置等持久化存储 |
 | Redis | 7-alpine | 会话缓存、事件总线(发布/订阅)、API限流 |
 | Nginx | latest | 前端静态资源服务(:8080)、后端API反向代理(:18080) |
 | Python | 3.11-slim | 后端API服务运行环境 |
 | Node.js | LTS | Docker镜像内前端构建（Dockerfile中安装） |
 ---
 ## 系统架构
 ### 架构设计图
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
 │                          用户浏览器                                  │
 │                    https://bot.qihuyun.com                          │
 └──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
 ┌──────────────────────────────────────────────────────────────────────┐
 │                    Docker: qihu-aiflow 容器                          │
 │                                                                      │
 │  ┌─────────────────────────────────────────────┐                    │
 │  │              Nginx (:8080)                    │                    │
 │  │  /            → frontend/dist (静态SPA)       │                    │
 │  │  /app/        → proxy localhost:18080/app/    │                    │
 │  └─────────────────────────────────────────────┘                    │
 │                        │                                             │
 │  ┌─────────────────────────────────────────────┐                    │
 │  │         FastAPI + Uvicorn (:18080)           │                    │
 │  │  ┌───────────┐ ┌──────────┐ ┌───────────┐  │                    │
 │  │  │ auth      │ │ chat     │ │ channels  │  │                    │
 │  │  │ knowledge │ │ market   │ │ token     │  │                    │
 │  │  │ payment   │ │ profile  │ │ assets    │  │                    │
 │  │  │ evolution │ │ admin/*  │ │ webhook   │  │                    │
 │  │  └───────────┘ └──────────┘ └───────────┘  │                    │
 │  │  ┌──────────────────────────────────────┐   │                    │
 │  │  │   平台适配器层                        │   │                    │
 │  │  │  feishu│wechat│dingtalk│slack│...    │   │                    │
 │  │  └──────────────────────────────────────┘   │                    │
 │  └─────────────────────────────────────────────┘                    │
 │                        │                                             │
 └────────────────────────┼─────────────────────────────────────────────┘
                         │
          ┌──────────────┴──────────────┐
          ▼                              ▼
 ┌──────────────────┐          ┌──────────────────┐
 │  MySQL 8.0       │          │  Redis 7         │
 │  :3306           │          │  :6379           │
 │  容器: qihu-     │          │  容器: qihu-     │
 │    aiflow-mysql  │          │    aiflow-redis  │
 └──────────────────┘          └──────────────────┘
 ━━━━━━━━━━━━━━━━ 外部集成 ━━━━━━━━━━━━━━━━
    ClawBot API           AI模型供应商          微信/支付宝
  (微信IM绑定)        (OpenAI兼容)            (支付网关)
 ```
 ### 请求流程
 ```
 用户请求 → Nginx(:8080) → /app/* → Uvicorn(:18080) → FastAPI路由
                                            ↓
                                     JWT认证中间件
                                            ↓
                                    SQLAlchemy ORM
                                    ↙           ↘
                              MySQL 8.0        Redis 7
 ```
 ### 数据隔离
 - 所有用户数据查询强制带 `user_id` 过滤，实现物理级数据隔离
 - 前后台权限分离：`role: admin` 可访问 `/admin/*` 路由
 - API密钥独立管理，支持颁发/撤销
 ---
 ## 功能模块
 ### 前台功能（10大模块）
 #### 1. AI聊天
 - 多模型对话：支持切换不同AI模型供应商和模型
 - 流式输出(SSE)：AI回复实时逐字展示
 - 知识库关联：选择知识库让AI基于专属知识回答
 - Agent/技能调用：Tool-call机制自动调用关联技能
 - 会话管理：创建/归档/置顶/搜索会话
 - 对话历史：完整的用户-AI对话记录
 #### 2. 频道（IM接入）
 - 多平台支持：飞书、微信、钉钉、WhatsApp、Telegram、Slack
 - **微信**: 对接ClawBot官方API，扫码绑定微信个人号
  - 调用 `POST /api/v1/wechat/qrcode` 获取官方二维码
  - 轮询 `POST /api/v1/wechat/qrcode/status` 等待扫码确认
  - 自动保存 bot_token/ilink_bot_id/baseurl 等凭据
  - 支持 `POST /api/v1/wechat/channel_reset` 重置通道
 - 统一Webhook端点：`POST /app/api/channels/webhook/{platform}` 接收各平台消息
 - AI行为配置：Bot前缀、流式输出、私聊/群聊策略、白名单
 - 平台适配器模式：签名验证 + 消息解析 + 统一格式
 - 频道成员管理：邀请/移除成员
 #### 3. 知识库
 - 文档上传管理：PDF/Word/TXT等多格式支持
 - 目录组织：多级目录结构管理文档
 - AI知识图谱：LLM自动提取实体和关系
 - Canvas可视化：节点拖拽、悬停高亮、点击详情
 - Pipeline自动构建：知识库变更触发自动更新
 #### 4. 应用市场
 - 应用浏览：分类展示，详情查看
 - 搜索去重：智能搜索，防止重复
 - 购买安装：付费后一键安装
 - 卸载管理：支持卸载后重新安装（状态重置）
 - 后台审核：应用上架审核流程
 #### 5. Token驾驶舱
 - 消耗概览：今日/累计/日均Token统计
 - 用量图表：按模型、日期维度可视化
 - CSV导出：消耗明细数据导出下载
 - 一键充值：快捷跳转付费中心
 - 服务器时间：上海时区(UTC+8)实时同步
 #### 6. 付费中心
 - 会员订阅：多等级会员体系（基础/高级/企业）
 - 增值服务：单项服务购买
 - 实名认证：身份信息验证
 - 支付集成：微信支付 + 支付宝双渠道
 - 自动续费：会员到期自动续订
 #### 7. 资产中心
 - 文件上传：支持多种格式
 - 分类管理：按文件类型自动归类
 - 在线预览：Office文档(Word/Excel/PPT) + PDF
 - AI图像生成：广告图/配图AI生成
 - 去重存储：按ID去重节省空间
 #### 8. AI进化
 - 进化Pipeline：自动化知识图谱构建流程
 - 配置管理：启动/停止/参数调整
 - 监控面板：Pipeline状态、进度实时展示
 - 自动恢复：系统重启后自动恢复运行中的Pipeline
 #### 9. 个人中心
 - 用户资料：修改头像、邮箱、手机号
 - 密码修改：安全的密码更新
 - 会员信息：等级、到期时间查看
 #### 10. 消息通知
 - 系统通知：平台公告、功能更新
 - 应用通知：安装/更新提醒
 - 付费通知：订单状态变更
 ### 后台管理（13大模块）
 #### 1. 平台驾驶舱
 - 核心指标：用户总数、活跃模型数、今日订单、Token消耗
 - Token统计面板：今日/累计/日均消耗，活跃模型数
 - 快捷入口：大模型库、网站设置、支付配置、增值服务等
 - 操作日志：最近管理员操作记录
 - 审计日志：安全审计追踪
 #### 2. 用户管理
 - 用户列表：搜索、筛选、分页
 - 角色管理：admin / user 角色分配
 - 状态管理：激活 / 封禁用户
 - 用户详情：基本信息、会员状态
 #### 3. 大模型库管理
 - 模型供应商：添加/编辑AI模型供应商
 - 模型配置：模型名称、API地址、API密钥
 - 默认模型：设置全局默认使用的模型
 #### 4. 供应商管理
 - 供应商配置：管理第三方AI服务提供商
 - API密钥管理：密钥加密存储
 #### 5. 网站基础设置
 - 站点信息：网站名称、Logo、描述
 - 邮件配置：SMTP服务器 + 测试发送
 - 短信配置：短信服务配置
 - AI内容生成：AI辅助生成网站文案
 #### 6. 支付渠道配置
 - 微信支付：商户号、API密钥配置
 - 支付宝：AppID、商户私钥配置
 #### 7. 增值服务管理
 - 服务列表：所有增值服务CRUD
 - 定价管理：服务价格设置
 - 上下架：控制服务可用状态
 #### 8. 会员订阅体系
 - 会员等级：多等级定义和权限
 - 订阅计划：时长、价格配置
 - 自动化规则：会员自动升级/降级
 #### 9. 广告位管理
 - Banner管理：图片上传、排序
 - AI图像生成：AI自动生成广告图
 - 投放配置：位置、展示频率
 #### 10. 应用市场审核
 - 应用审核：审核上架应用
 - 优惠券管理：创建/发放优惠券
 #### 11. 频道管理
 - 频道监控：查看所有频道状态
 - 平台配置：各平台接入凭证和AI行为配置
 #### 12. 知识库管理
 - 知识库概览：查看系统所有知识库
 - 文档管理：文档列表和状态
 #### 13. 日志与风控
 - 操作日志：管理员操作审计
 - API调用日志：接口调用统计
 - 付费日志：订单和交易记录
 ---
 ## Docker 部署手册
 ### 前置条件
 - Docker Engine 20.10+
 - Docker Compose v2+
 - 可用磁盘空间 ≥ 10GB
 - 宿主机端口：12888（前端）、18080（后端）、3306（MySQL）、6379（Redis）
 ### 方式一：从 Git 仓库部署
 ```bash
 # 1. 克隆仓库
 git clone http://git.qihuyun.com/qyyfw/qihuaiflow.git
 cd qihuaiflow
-# 2. 构建并启动所有服务（MySQL + Redis + AIFlow）
+# 2. 配置环境
-docker compose up -d --build
+cp .env.example .env  # 编辑 API keys
-# 3. 等待服务就绪（首次构建约3-5分钟）
+# 3. 一行启动
-# 查看日志确认启动完成
+docker-compose up -d
 docker compose logs -f aiflow
-# 4. 访问系统
+# 4. 访问
-# 前端: http://<宿主机IP>:12888
+open https://ai.qihuyun.com          # 前台
-# 默认账号: admin / admin123
+open https://ai.qihuyun.com/admin    # 后台
 ```
-### 方式二：从程序包部署
+**前置要求**: Docker Compose v2 + 8GB RAM
-```bash
+---
 # 1. 解压程序包
 tar -xzf Qihu-aiflow.tar.gz
 cd <解压目录>
-# 2. 修改环境变量（可选，编辑 .env 或 docker-compose.yml）
+## ✨ 核心能力
 # vim .env
-# 3. 构建并启动
+| 能力 | 描述 | 状态 |
 docker compose up -d --build
 # 4. 验证
 curl http://localhost:12888/         # 前端
 curl http://localhost:18080/app/api/health  # 后端
 ```
 ### Docker Compose 自动执行流程
 `docker compose up -d --build` 启动后会自动：
 1. **拉取基础镜像**: python:3.11-slim, mysql:8.0, redis:7-alpine
 2. **构建AIFlow镜像**:
   - 安装系统依赖 (nginx, mysql-client, redis-tools, build-essential)
   - 安装 Python 依赖 (requirements.txt, 使用清华镜像源)
   - 安装 Node.js + npm，构建前端 `npm install && npm run build`
   - 配置 Nginx 反向代理
 3. **启动MySQL**: 等待健康检查通过 (mysqladmin ping)
 4. **启动Redis**: 密码认证 (requirepass pwd2026)
 5. **初始化数据库**:
   - 创建数据库 `aiflow` (utf8mb4)
   - 按序执行 migrations/ 下 15 个 SQL 迁移脚本
   - 智能检测 admin 密码哈希有效性，仅在无效时重置
 6. **启动应用**: Nginx(:8080) + Uvicorn(:18080)
 ### 端口说明
 | 端口 | 服务 | 说明 |
 |------|------|------|
-| 12888 | Nginx (前端) | 用户浏览器访问端口 |
+| 🤖 **AI 对话** | SSE 流式对话、多模型自动路由、Markdown 渲染、代码高亮 | ✅ 生产 |
-| 18080 | Uvicorn (后端API) | API服务端口 |
+| 📚 **知识库 RAG** | 文档上传 → 切片 → pgvector 向量化 → BM25+语义检索 | ✅ 生产 |
-| 3306 | MySQL | 数据库端口 |
+| 🛒 **技能市场** | 97+ Skill 发现-安装-执行，Meilisearch 中文搜索，14 类 capability | ✅ 生产 |
-| 6379 | Redis | 缓存端口 |
+| 🎨 **媒体生成** | 图片/视频 AI 生成，media relay 中转，微信内联渲染 | ✅ 生产 |
 | 📊 **Token 驾驶舱** | 实时用量监控、趋势图表、预警告警、计费追踪 | ✅ 生产 |
 | 💰 **会员订阅** | 多套餐对比、微信支付、增值单点付费 | ✅ 生产 |
 | 🏪 **应用市场** | 第三方应用集成，产品定价，webhook 回调 | ✅ 生产 |
 | 🤖 **Agent 编排** | DAG 图引擎 + Supervisor 模式 | 🔨 迭代中 |
 | 📱 **IM Bot** | 微信扫码连接，AI 对话 + 图片生成 | ✅ 生产 |
 | 🛡️ **安全纵深** | 四层防护: 限流+扫描器拦截+IP黑名单+JWT认证 | ✅ 生产 |
-**注意**: 前端映射到宿主机 12888 端口（而非 8080），用户访问: `http://<IP>:12888`
+---
-### 环境变量配置
+## 🏗️ 架构总览
-Docker Compose 环境变量在 `docker-compose.yml` 的 `environment` 段配置：
+```
 ┌──────────────────────────────────────────────────┐
 │          React SPA (Vite 5 + Tailwind 4)          │
 │  Landing | Chat | Knowledge | Market | Agent      │
 ├──────────────────────────────────────────────────┤
 │          Nginx (限流 + 扫描器 + SSL)               │
 ├──────────────────────────────────────────────────┤
 │          FastAPI uvicorn (Python 3.11)             │
 │  EngineCore (双 Claw 单引擎) | LLM Router         │
 ├──────────────────────────────────────────────────┤
 │    LiteLLM      │  MCP SDK   │  Casdoor OAuth     │
 │   (模型网关)     │ (工具协议) │  (统一认证)        │
 ├──────────────────────────────────────────────────┤
 │  PostgreSQL+pgvector │ Redis │ Meilisearch        │
 └──────────────────────────────────────────────────┘
 ```
-| 变量 | 说明 | Docker默认值 | 本地默认值 |
+详见 [ARCHITECTURE.md](ARCHITECTURE.md)
 |------|------|-------------|-----------|
 | `MYSQL_HOST` | MySQL地址 | mysql (容器名) | localhost |
 | `MYSQL_PORT` | MySQL端口 | 3306 | 3306 |
 | `MYSQL_USER` | MySQL用户名 | root | root |
 | `MYSQL_PASSWORD` | MySQL密码 | pwd2026 | pwd2026 |
 | `MYSQL_DATABASE` | 数据库名 | aiflow | aiflow |
 | `REDIS_HOST` | Redis地址 | redis (容器名) | localhost |
 | `REDIS_PORT` | Redis端口 | 6379 | 6379 |
 | `REDIS_PASSWORD` | Redis密码 | pwd2026 | pwd2026 |
 | `SECRET_KEY` | JWT签名密钥 | (固定值) | (固定值) |
 | `APP_ACCESS_URL` | 外网访问地址 | https://bot.qihuyun.com | https://bot.qihuyun.com |
 | `DEBUG` | 调试模式 | false | false |
-**重要**: 生产环境请修改 `SECRET_KEY`、`MYSQL_PASSWORD`、`REDIS_PASSWORD`。
+---
-### 管理员账号
+## 📦 技术栈
-部署后默认管理员账号：
+| 层 | 技术 |
 |----|------|
 | 前端 | React 18 + TypeScript 5.6 + Vite 5 + Tailwind CSS 4 + Zustand 5 |
 | 后端 | Python 3.11 + FastAPI + SQLAlchemy 2.0 + Pydantic |
 | 数据库 | PostgreSQL 18 + pgvector (向量) + Redis 7 (缓存) |
 | 认证 | Casdoor (OAuth2/OIDC) + JWT |
 | LLM 网关 | LiteLLM (模型路由 + 费用追踪 + 协议转换) |
 | 搜索引擎 | Meilisearch v1.11 (BM25 + jieba 中文分词) |
 | 可观测 | Prometheus + Grafana + Alloy (OTel) |
 | 部署 | Docker Compose (一行启动，自包含) |
 | 设计 | qihu-design-system (53 modules, indigo #5B5FED) |
-| 用户名 | 密码 | 角色 |
+---
 |--------|------|------|
 | admin | admin123 | 超级管理员 |
-> 首次登录后请立即修改密码：进入「个人中心」页面进行修改。
+## 🗂️ 项目结构
 > run.sh 会智能检测密码哈希有效性——如果用户已修改密码（有效bcrypt哈希），则保持不变。
-### 常用命令
+```
 qihuaiflow/
 ├── backend/python/app/        # FastAPI 后端
 │   ├── api/                   # API 路由
 │   │   ├── admin/             # 后台管理 API (models/skills/agents/users/...)
 │   │   ├── chat.py            # AI 对话核心 (SSE流式 + 媒体生成)
 │   │   ├── auth.py            # JWT 认证
 │   │   └── im_llm.py          # IM Bot LLM 薄壳
 │   ├── core/                  # 核心引擎
 │   │   ├── llm_router.py      # LLM 路由 + 熔断
 │   │   ├── claw_adapters.py   # 双 Claw 适配器 (SSE/Buffer)
 │   │   ├── litellm_sync.py    # LiteLLM 模型同步服务
 │   │   ├── node_registry.py   # Agent 节点注册
 │   │   └── capability_discovery.py  # 能力发现
 │   └── models/                # 数据库模型
 ├── frontend/                  # React 前端
 │   └── src/
 │       ├── pages/admin/       # 后台页面 (39 modules)
 │       ├── pages/front/       # 前台页面
 │       ├── components/        # 设计系统组件
 │       │   ├── ui/            # Button/Badge/Input/Card
 │       │   ├── canvas/        # GenUiCard/StatusRing/ChatComposer
 │       │   └── layout/        # AppShell/ThemeToggle
 │       └── styles/            # 全局 CSS + chat 样式
 ├── nginx/                     # Nginx 配置文件
 ├── config/                    # LiteLLM + 平台配置
 ├── migrations/                # 数据库迁移 SQL
 ├── docker-compose.yml         # Docker Compose 编排
 ├── Dockerfile                 # 主应用镜像
 ├── ARCHITECTURE.md            # 架构设计文档
 └── DESIGN.md                  # 设计系统规范
 ```
 ---
 ## 🔧 开发指南
 ### 环境要求
 - Docker Compose v2
 - Python 3.11+ (本地开发)
 - Node.js 22+ (前端开发)
 - Git
 ### 本地开发
 ```bash
-# 查看所有容器状态
+# 后端
-docker compose ps
+cd backend/python
 pip install -r requirements.txt
 uvicorn main:app --reload --port 18080
-# 查看应用日志
+# 前端
-docker compose logs -f aiflow
+cd frontend
 npm install
 npm run dev  # Vite dev server :5173
 ```
-# 查看MySQL日志
+### 部署
 docker compose logs -f mysql
-# 重启应用
+```bash
-docker compose restart aiflow
+# 生产部署
 docker-compose up -d --build
-# 停止所有服务
+# 查看状态
-docker compose down
+docker-compose ps
 docker logs qihu-aiflow --tail 50
-# 停止并清除数据（危险！）
+# 重启
-docker compose down -v
+docker restart qihu-aiflow
 ```
-# 重新构建并启动
+### 测试
 docker compose up -d --build
-# 进入应用容器
+```bash
-docker exec -it qihu-aiflow bash
+# 后端测试
 docker exec qihu-aiflow bash -c "cd /app/backend/python && .venv/bin/python -m pytest"
 # 当前: 165 passed / 2 skipped
-# 进入MySQL
+# 前端测试
-docker exec -it qihu-aiflow-mysql mysql -u root -ppwd2026 aiflow
+docker exec qihu-aiflow bash -c "cd /app/frontend && npx vitest run"
 # 进入Redis
 docker exec -it qihu-aiflow-redis redis-cli -a pwd2026
 ```
 ---
-## 项目文件结构
+## 📊 平台数据
-```
+| 指标 | 数值 |
 /
 ├── frontend/                    # 前端项目 (React + TypeScript)
 │   ├── dist/                    # 构建产物（Docker构建时生成）
 │   ├── public/                  # 静态资源
 │   ├── src/                     # TypeScript源码
 │   │   ├── api/                 # API客户端 (index.ts)
 │   │   ├── components/          # 通用组件 (layout/)
 │   │   ├── contexts/            # React上下文
 │   │   ├── hooks/               # 自定义Hooks
 │   │   ├── mock/                # Mock数据（开发用）
 │   │   ├── pages/               # 页面组件
 │   │   │   ├── admin/           # 后台管理页面
 │   │   │   └── front/           # 前台页面
 │   │   ├── styles/              # 全局样式
 │   │   └── types/               # TypeScript类型定义
 │   ├── package.json             # 前端依赖配置
 │   ├── package-lock.json        # 依赖锁文件
 │   └── vite.config.ts           # Vite构建配置
 ├── backend/python/              # 后端项目 (Python FastAPI)
 │   ├── main.py                  # 应用入口 (FastAPI app)
 │   ├── requirements.txt         # Python依赖列表
 │   └── app/                     # 应用核心代码
 │       ├── api/                 # API路由模块
 │       │   ├── auth.py          # 认证 (login/register)
 │       │   ├── chat.py          # AI聊天 (SSE流式)
 │       │   ├── channels.py      # IM频道管理 (ClawBot对接)
 │       │   ├── knowledge.py     # 知识库管理
 │       │   ├── market.py        # 应用市场
 │       │   ├── token_usage.py   # Token统计
 │       │   ├── payment.py       # 付费中心
 │       │   ├── profile.py       # 个人中心
 │       │   ├── assets.py        # 资产管理
 │       │   ├── evolution.py     # AI进化
 │       │   ├── notifications.py # 消息通知
 │       │   └── admin/           # 后台管理API
 │       │       ├── dashboard.py      # 驾驶舱
 │       │       ├── users.py          # 用户管理
 │       │       ├── models.py         # 模型管理
 │       │       ├── settings.py       # 网站设置
 │       │       ├── payment_admin.py  # 支付配置
 │       │       ├── services.py       # 增值服务
 │       │       ├── membership_admin.py # 会员管理
 │       │       ├── ads.py            # 广告管理
 │       │       ├── market_admin.py   # 应用审核
 │       │       └── logs.py           # 日志风控
 │       ├── models.py            # SQLAlchemy数据模型 (全部表定义)
 │       ├── database.py          # 数据库连接配置
 │       ├── config.py            # 应用配置
 │       ├── auth.py              # JWT认证 & 权限控制
 │       ├── middleware/          # 中间件
 │       │   ├── log_middleware.py # API追踪中间件
 │       │   └── log_service.py   # 操作日志服务
 │       ├── services/            # 业务服务
 │       │   └── evolution_service.py # 进化Pipeline服务
 │       ├── platform_adapter.py  # 平台适配器基类
 │       └── platform_adapters/   # 各平台适配器实现
 │           ├── feishu_adapter.py
 │           ├── wecom_adapter.py
 │           ├── dingtalk_adapter.py
 │           ├── whatsapp_adapter.py
 │           ├── telegram_adapter.py
 │           └── slack_adapter.py
 ├── migrations/                  # 数据库迁移脚本 (001-015)
 │   ├── 001_init.sql             # 初始化表结构
 │   ├── 002_init_data.sql        # 初始数据
 │   ├── ...
 │   └── 015_production_fixes.sql # 生产修复
 ├── docs/                        # 项目文档
 │   ├── PRD.md                   # 产品需求文档
 │   ├── PRD-self-evolution.md    # AI自进化PRD
 │   ├── PRD-self-evolution-v2.md # AI自进化PRD v2
 │   └── frontend-dev-record.md   # 前端开发记录
 ├── Dockerfile                   # Docker镜像构建文件
 ├── docker-compose.yml           # Docker Compose编排配置
 ├── nginx.conf                   # Nginx反向代理配置
 ├── run.sh                       # 一键启动脚本
 ├── .env                         # 环境变量配置
 ├── .gitignore                   # Git忽略配置
 ├── .dockerignore                # Docker构建忽略配置
 ├── VERSION                      # 版本信息
 ├── CHANGELOG.md                 # 变更日志
 └── README.md                    # 项目文档（本文件）
 ```
 ---
 ## API接口概览
 所有接口以 `/app/api/` 为前缀，完整OpenAPI文档访问: `http://<host>:18080/docs`
 | 模块 | 基础路径 | 主要接口 |
 |------|---------|---------|
 | 认证 | `/app/api/auth` | login, register, logout, me |
 | AI聊天 | `/app/api/chat` | conversations CRUD, messages, SSE流式 |
 | 频道 | `/app/api/channels` | channels CRUD, webhook, 扫码授权, 状态轮询 |
 | 知识库 | `/app/api/knowledge` | bases CRUD, documents, directories, graph |
 | 应用市场 | `/app/api/market` | apps, install, uninstall |
 | Token | `/app/api/token` | overview, stats, export CSV |
 | 付费 | `/app/api/payment` | plans, orders, realname verification |
 | 资产 | `/app/api/assets` | files CRUD, upload, preview |
 | 进化 | `/app/api/evolution` | configs, pipeline status |
 | 后台-仪表盘 | `/app/api/admin/dashboard` | stats, charts |
 | 后台-用户 | `/app/api/admin/users` | users CRUD |
 | 后台-模型 | `/app/api/admin/models` | providers, models CRUD |
 | 后台-设置 | `/app/api/admin/settings` | site, email, sms config |
 | 后台-支付 | `/app/api/admin/payment` | payment channel config |
 | 后台-日志 | `/app/api/admin/logs` | operation, api, payment logs |
 ---
 ## 数据库迁移
 | 编号 | 说明 |
 |------|------|
-| 001 | 初始化表结构（users, conversations, messages, channels等） |
+| LLM 模型数 | 14 (含 OCR/Rerank/Embedding/TTS/ASR) |
-| 002 | 初始数据（admin账号, 默认模型供应商, 种子数据） |
+| 技能数 | 97 |
-| 003 | 增值服务表 |
+| MCP 工具数 | 26 |
-| 004 | OAuth状态字段 |
+| 后台管理页面 | 39 |
-| 005 | 频道扩展字段（account_name, features） |
+| API 端点 | 300+ |
-| 006 | API调用统计表 |
+| 容器数 | 12 |
-| 007 | 进化系统基础表 |
+| 代码行数 | 50,000+ |
 | 008 | 进化系统v2（EvolutionWatcher状态管理） |
 | 009 | 支付实名认证字段 |
 | 010 | 默认模型字段 |
 | 011 | 知识库存储与资产表 |
 | 012 | 生产环境列同步（幂等补全） |
 | 013 | 知识图谱表（节点/边/构建记录） |
 | 014 | 测试数据清理 |
 | 015 | 生产修复（content列 + AppPurchase状态重置） |
 ---
-## 更新日志
+## 🌐 线上环境
-详见 `VERSION` 和 `CHANGELOG.md`。
+| 资源 | 地址 |
 |------|------|
 | 前台 | https://ai.qihuyun.com |
 | 后台 | https://ai.qihuyun.com/admin |
 | Grafana | http://210.16.161.218:3000 |
 | Prometheus | http://210.16.161.218:9090 |
 | Casdoor | http://210.16.161.218:8000 |
 | Git 仓库 | http://git.qihuyun.com/qyyfw/qihuaiflow |
-### v2.0.1 (2026-06-02)
+---
- 微信ClawBot官方API标准重构（频道扫码绑定）
+## 📝 更新日志
- 6项生产缺陷修复（二维码、知识库、tool-call、应用安装、时区、邮件）
+
- 完整项目文档（README.md）
+详见 [CHANGELOG.md](CHANGELOG.md) 和 [RELEASES.md](RELEASES.md)
- Gitea仓库发布
+
 **v3.0 重点更新 (2026-08-12)**:
 - ✅ 修复 `/admin/models` 空白页 (React hooks + 缓存问题)
 - ✅ 实现 LiteLLM 模型同步 (管理员 UI → LiteLLM REST API)
 - ✅ 实现 media_relay 端点 (微信 Bot 图片中转)
 - ✅ 设计系统全量收口 + ErrorBoundary + safeLazy
 - ✅ Docker Compose STORE_MODEL_IN_DB 模式
 - ✅ Nginx 限流 + 扫描器拦截 + IP 黑名单
 ---
 ## 📄 许可证
 私有项目。© 2026 七虎AI. All rights reserved.
@@ -1,84 +1,93 @@
-# 七虎AI PaaS 平台 — 架构设计与实施方案 v2.0
+# 七虎AI PaaS 平台 — 架构设计与实施方案 v3.0
-> **最后更新**: 2026-07-27
+> **最后更新**: 2026-08-12
-> **版本**: v2.0
+> **版本**: v3.0
-> **用途**: 投喂 AI 大模型进行平台竞争力、护城河、扩展能力分析
+> **用途**: 平台竞争力、护城河、技术框架、功能架构、业务逻辑完整文档
 > **维护**: 随系统迭代实时更新
 > **仓库**: http://git.qihuyun.com/qyyfw/qihuaiflow
 ---
-## 一、平台概述
+## 一、平台护城河 (Moat)
-### 1.1 定位
+### 1.1 核心竞争壁垒
-七虎AI（qihuyun.com）是一个面向开发者和企业的 **AI PaaS 平台**，核心能力是聚合多厂商大模型、提供标准化工具调用层、支持 Skill/MCP/Agent 的发现-安装-编排-执行全生命周期管理。
+| 壁垒维度 | 具体实现 | 竞争门槛 |
 |---------|---------|---------|
 | **模型聚合网关** | LiteLLM + STORE_MODEL_IN_DB，4+ 厂商统一 OpenAI 协议，管理员 UI 一键增删模型自动同步 | 竞品需手动配置模型路由，无 admin UI 驱动 |
 | **双 Claw 单引擎** | Web SSE + IM Bot (微信) 共享 `EngineCore._send_message_core`，能力发现、MCP 调用、LLM 路由只实现一次 | 竞品 Web/IM 两套代码，同步成本高 |
 | **技能市场闭环** | Skills 发现-安装-搜索(Meilisearch)-执行全生命周期，支持 97+ 技能、14 类 capability | 需自建市场 + 搜索引擎 + 沙箱执行 |
 | **ngnix 安全纵深** | 四层防护: 限流(API 30r/s/Admin 5r/s/Login 1r/s) + 扫描器拦截(14类path/20类UA) + 自动IP黑名单(5min cron/24h TTL) + SSL终止 | 竞品大多只做限流 |
 | **模型双轨制已消除** | #965 平台→LiteLLM REST API 同步，管理员 UI 操作即生效，不再 SSH 手动改 yaml | 多数平台仍手动配置网关 |
 | **设计语言系统** | 完整 `qihu-design-system` (53 modules, CSS 55KB, 品牌色 #5B5FED + 渐变 + 玻璃/辉光 + 暗态) | 需专业设计师 + 前端团队长期维护 |
 | **可观测性** | Prometheus+Grafana+Alloy OTel 双 Claw 标签看板 + 日志审计 | 中小企业平台通常缺监控 |
-### 1.2 核心价值主张
+### 1.2 竞争策略
-| 价值维度 | 实现方式 |
+| 策略 | 我方 | 竞品(AI PaaS) | 竞品(垂直SaaS) |
-|---------|---------|
+|------|------|-------------|-------------|
-| 模型聚合 | 统一 OpenAI 兼容协议接入 4+ 厂商（SiliconFlow、MiMo、AGNES、DeepSeek），自动 failover |
+| 模型数量 | 14+ 实时可增删 | 3-5 个 | 1 个 |
-| 技能市场 | Skills 的上架-搜索-安装-执行闭环，支持 14 个能力分类 |
+| 技能市场 | 97 个，自建生态 | 0-20 个 | 无 |
-| MCP 协议 | 官方 Anthropic MCP SDK 实现，支持 streamable_http/SSE 传输 |
+| IM Bot | 微信 + 企业微信扩展 | 无 | 自己开发 |
-| Agent 编排 | DAG 图引擎 + Supervisor 模式，支持外部 Agent（Dify/n8n/Coze）远程调用 |
+| 多租户 | PG RLS 行级安全 | 应用层隔离 | 单租户 |
-| IM Bot | 多平台（微信/企业微信/飞书/QQ）统一消息网关 |
+| 部署 | Docker Compose 一行启动 | Kubernetes 复杂 | 无 Docker |
-| 知识库 RAG | PostgreSQL pgvector + 混合检索 |
+| 定价 | 免费层 + 会员订阅 | 仅付费 | 固定价 |
 | 媒体生成 | 异步图片/视频生成（后台线程，不阻塞 SSE） |
 | 可观测 | Prometheus+Grafana 监控栈 + 日志审计 |
 ---
-## 二、整体架构
+## 二、部署架构
-### 2.1 部署架构
+### 2.1 物理拓扑
 ```
                    Internet
                        │
-                   ┌────▼────┐
+              ┌─────────▼─────────┐
-                   │  Nginx  │  :12888 (HTTPS)
+              │ 宝塔 Nginx :443    │ SSL 终止 + 反向代理
-                   └────┬────┘
+              │ root: /www/dk_    │
-                        │
+              │  project/wwwroot/  │
              │  ai.qihuyun.com   │
              └─────────┬─────────┘
                        │ :12888
         ┌──────────────┼──────────────┐
         │              │              │
-    ┌────▼────┐    ┌───▼────┐    ┌───▼─────┐
+    ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐
-    │ React   │    │FastAPI │    │ Casdoor │
+    │ Nginx    │  │ uvicorn  │  │ 静态资源 │
-    │ Vite    │    │uvicorn │    │  :8000  │
+    │ :8080    │  │ :18080   │  │ dist/    │
-    │ (dist/) │    │:18080  │    └─────────┘
+    │ proxy_pass  │ FastAPI  │  │ React SPA│
-    └─────────┘    └───┬────┘
+    └──────────┘  └────┬─────┘  └──────────┘
                       │
-         ┌─────────────┼─────────────┐
+         ┌─────────────┼─────────────────┐
         │             │                 │
-    ┌────▼────┐   ┌───▼────┐   ┌───▼──────┐
+    ┌────▼────┐   ┌───▼────┐       ┌────▼─────┐
-    │Postgres │   │ Redis  │   │ Executor │
+    │Postgres │   │ Redis  │       │LiteLLM   │
-    │PG18+    │   │:6379   │   │ (Code)   │
+    │PG18     │   │ :6379  │       │ :4000    │
-    │pgvector │   └────────┘   └──────────┘
+    │+pgvector│   └────────┘       │ LLM 网关 │
-    └─────────┘
+    └─────────┘                    └──────────┘
 ```
-### 2.2 容器清单
+### 2.2 容器清单 (Docker Compose)
-| 容器 | 镜像 | 用途 |
+| 容器 | 镜像 | 端口 | 用途 |
-|------|------|------|
+|------|------|------|------|
-| qihu-aiflow | 自建(custom) | 主应用（Nginx + FastAPI uvicorn + React dist） |
+| **qihu-aiflow** | qihuaiflow:with-deps | 12888/18080/8080 | 主应用: Nginx + FastAPI + React dist |
-| qihu-aiflow-pg18 | pgvector/pgvector:pg16 | PostgreSQL 主库 + 向量扩展 |
+| **qihu-aiflow-litellm** | berriai/litellm:main-stable | 14000→4000 | LLM 网关 + DB 模式模型管理 |
-| qihu-aiflow-redis | redis:7-alpine | 缓存/队列/会话 |
+| **qihu-aiflow-pg18** | pgvector/pgvector:pg16 | 5432 | PostgreSQL 主库 + 向量引擎 |
-| qihu-aiflow-casdoor | casdoor | 统一认证 |
+| **qihu-aiflow-redis** | redis:7-alpine | 6379 | 缓存/队列/会话 |
-| qihuaiflow-executor | 自建 | 代码执行沙箱 |
+| **qihu-aiflow-casdoor** | casdoor | 8000 | 统一认证 OAuth2/OIDC |
-| qihu-aiflow-prometheus | prom/prometheus | 指标采集 |
+| **qihu-aiflow-meilisearch** | meilisearch:v1.11 | 17700 | 技能市场搜索引擎 |
-| qihu-aiflow-grafana | grafana/grafana | 可视化监控 |
+| **qihu-aiflow-prometheus** | prom/prometheus | 9090 | 指标采集 |
-| qihu-aiflow-alloy | grafana/alloy | 日志采集 Agent |
+| **qihu-aiflow-grafana** | grafana/grafana | 3000 | 可视化看板 |
-| qihu-aiflow-node-exporter | prom/node-exporter | 宿主机指标 |
+| **qihu-aiflow-alloy** | grafana/alloy | - | 日志采集 Agent |
 | **qihu-aiflow-node-exporter** | prom/node-exporter | 9100 | 宿主机指标 |
-### 2.3 数据流
+### 2.3 网络与域名
-```
+| 域名 | 用途 |
-用户请求 → Nginx(:12888) → uvicorn(:18080)
+|------|------|
-  ├── /app/api/chat/* → chat.py (SSE streaming)
+| ai.qihuyun.com | 主站 (React SPA + FastAPI API) |
-  ├── /app/api/auth/* → auth.py (JWT)
+| docs.qihuyun.com | 文档站 |
-  ├── /app/api/admin/* → admin/* (CRUD + 管理)
+| bot.qihuyun.com | Bot 回调地址 |
  └── / → index.html → React SPA
 ```
 ---
@@ -86,459 +95,322 @@
 | 层级 | 技术 | 版本 | 选型理由 |
 |------|------|------|---------|
-| 后端框架 | FastAPI (Python) | 0.115+ | 异步原生、SSE 流式支持、Pydantic 验证 |
+| **后端框架** | FastAPI (Python 3.11) | 0.115+ | 异步原生、SSE 流式、Pydantic 验证、自动 OpenAPI |
-| ASGI 服务器 | uvicorn | 0.30+ | 单进程事件循环、生产级 |
+| **ASGI 服务器** | uvicorn | 0.30+ | 单进程事件循环、生产级 |
-| 前端框架 | React + Vite | 18 + 5 | 组件化、HMR 热更新、Tree-shaking |
+| **前端框架** | React + Vite | 18.3 + 5.4 | 组件化、HMR、TypeScript 5.6 严格模式 |
-| 前端语言 | TypeScript | 5.6+ | 类型安全 |
+| **前端构建** | Tailwind CSS v4.3 | @tailwindcss/vite | utility-first, design token 驱动 |
-| 关系数据库 | PostgreSQL | 18 | JSONB、pgvector 原生支持、AIO 引擎 |
+| **状态管理** | Zustand 5 | persist | 轻量级，三态主题 (light/dark/system) |
-| 向量引擎 | pgvector | 0.8.4 | 与主库同集群、免运维 |
+| **关系数据库** | PostgreSQL 18 | pgvector 0.8.4 | JSONB、向量原生命支持 |
-| 缓存 | Redis | 7 | 会话、队列、工具列表缓存 |
+| **向量引擎** | pgvector | 0.8.4 | 与主库同集群、混合检索 BM25+语义 |
-| 认证 | Casdoor | latest | 开源统一认证、OAuth2/OIDC |
+| **缓存/队列** | Redis 7 | - | 会话、工具列表缓存、事件总线 |
-| ORM | SQLAlchemy | 2.0.36 | 成熟生态、支持 async |
+| **认证** | Casdoor | latest | OAuth2/OIDC、自建身份提供商 |
-| LLM 客户端 | openai Python SDK | 1.x | OpenAI 兼容协议统一接入 |
+| **ORM** | SQLAlchemy 2.0 | 2.0.36 | 成熟生态、async 支持、psycopg |
-| MCP 客户端 | mcp Python SDK | 1.28.1 | Anthropic 官方 SDK |
+| **LLM 客户端** | openai Python SDK | 1.x | 统一 OpenAI 协议接入 |
-| 代理 | Nginx | 1.25+ | 反向代理、静态文件、SSL |
+| **LLM 网关** | LiteLLM | main-stable | 模型路由、协议转换、费用追踪、key 管理 |
-| 容器 | Docker Compose | v2 | 单机编排 |
+| **MCP 客户端** | mcp Python SDK | 0.28.1 | Anthropic 官方 SDK、streamable_http/SSE |
-| 监控 | Prometheus + Grafana | latest | 开源标准、全栈可见 |
+| **搜索引擎** | Meilisearch | v1.11 | BM25 + jieba 中文分词、sub-50ms 响应 |
 | **代理** | Nginx | 1.25+ | 反向代理、静态文件、SSL、限流、扫描器拦截 |
 | **可观测** | Prometheus + Grafana | latest | 指标仪表盘、双 Claw OTel 标签 |
 | **容器** | Docker Compose | v2 | 单机部署、一行启动 |
 ---
-## 四、数据模型（67 张表，按域分组）
+## 四、功能架构
-### 4.1 核心业务域
+### 4.1 系统分层
 | 表名 | 说明 | 关键字段 |
 |------|------|---------|
 | users | 用户 | id, username, password_hash, role |
 | conversations | 对话 | id, user_id, title, model_id |
 | messages | 消息 | id, conv_id, role, content, tool_calls, used_skills |
 | models | AI 模型 | id, provider_id, name, endpoint, capabilities, is_default |
 | model_providers | 模型提供商 | id, name, protocol, api_key, api_base_url, auth_header |
 | site_settings | 站点配置 | key, value (JSON) |
 | mcpservers | MCP 服务 | id, name, url, transport_type, is_enabled, tools_count |
 ### 4.2 技能市场域
 | 表名 | 说明 |
 |------|------|
 | market_apps | 市场应用（Skills/MCP/Agents） |
 | market_app_versions | 应用版本 |
 | app_purchases | 购买记录 |
 | app_reviews | 评价 |
 | app_installations | 安装记录 |
 | skill_versions | 技能版本 |
 | skill_publish_records | 发布记录 |
 | evolution_skills | 进��技能 |
 | evolution_events | 进化事件 |
 | evolution_trajectories | 进化轨迹 |
 | team_shared_skills | 团队共享技能 |
 ### 4.3 知识库域
 | 表名 | 说明 |
 |------|------|
 | knowledge_bases | 知识库 |
 | knowledge_directories | 知识目录 |
 | knowledge_documents | 文档 |
 | knowledge_document_chunks | 文档分块 |
 | knowledge_graph_nodes | 知识图谱节点 |
 | knowledge_graph_edges | 知识图谱边 |
 | external_kb_services | 外部 KB 服务 |
 ### 4.4 会员/支付域
 | 表名 | 说明 |
 |------|------|
 | membership_plans | 会员计划 |
 | membership_subscriptions | 订阅 |
 | orders | 订单 |
 | coupons | 优惠券 |
 | user_coupons | 用户优惠券 |
 | value_added_services | 增值服务 |
 | payment_configs | 支付配置 |
 ### 4.5 监控/运维域
 | 表名 | 说明 |
 |------|------|
 | token_usage_logs | Token 用量日志 |
 | token_balances | 余额 |
 | operation_logs | 操作日志 |
 | audit_logs | 审计日志 |
 | login_logs | 登录日志 |
 | risk_rules | 风控规则 |
 | slow_request_logs | 慢请求日志 |
 | api_call_stats | API 调用统计 |
 | task_execution_logs | 任务执行日志 |
 ---
 ## 五、API 全景
 ### 5.1 前台 API（用户面）
 | 路由前缀 | 端点 | 方法 | 说明 |
 |---------|------|------|------|
 | /app/api/auth | /login | POST | 用户登录，返回 JWT |
 | /app/api/auth | /register | POST | 注册 |
 | /app/api/chat | /conversations | GET/POST | 对话列表/创建 |
 | /app/api/chat | /conversations/{id}/messages | POST | 发送消息（非流式） |
 | /app/api/chat | /conversations/{id}/messages/stream | POST | **SSE 流式聊天** |
 | /app/api/chat | /models | GET | 可用模型列表 |
 | /app/api/chat | /media/relay | GET | 媒体代理 |
 | /app/api/market | /apps | GET | 应用市场列表 |
 | /app/api/market | /apps/{id} | GET | 应用详情 |
 | /app/api/knowledge | /search | POST | 知识库搜索 |
 ### 5.2 后台 API（管理面）
 | 路由前缀 | 说明 |
 |---------|------|
 | /app/api/admin/users | 用户管理 |
 | /app/api/admin/models | 模型管理 |
 | /app/api/admin/skills | 技能管理 |
 | /app/api/admin/agents | Agent 管理 |
 | /app/api/admin/mcp | MCP 服务管理 |
 | /app/api/admin/workflow | 工作流管理 |
 | /app/api/admin/market | 市场管理 |
 | /app/api/admin/analytics | 数据分析 |
 | /app/api/admin/developer | 开发者 API |
 | /app/api/admin/settings | 站点设置 |
 | /app/api/admin/storage | 存储管理 |
 | /app/api/admin/logs | 日志查看 |
 | /app/api/admin/automation | 自动化任务 |
 ### 5.3 SSE 事件类型
 ```
-POST /conversations/{id}/messages/stream
+┌─────────────────────────────────────────────────┐
-Content-Type: text/event-stream
+│                  表现层 (Frontend)                │
-
+│  React SPA | Tailwind CSS | Zustand State        │
-事件帧:
+│  AppShell (NavRail+抽屉) | 三态主题              │
-  data: {"type":"reasoning","content":"..."}   // 模型推理过程
+├─────────────────────────────────────────────────┤
-  data: {"type":"delta","content":"..."}        // 逐字回复增量  
+│                  网关层 (Gateway)                 │
-  data: {"type":"step","step":{...}}            // 工具调用步骤
+│  Nginx | SSL 终止 | 限流 | 扫描器拦截 | IP 黑名单 │
-    step.type: "thinking" | "skill" | "mcp"
+├─────────────────────────────────────────────────┤
-  data: {"type":"done","message_id":"..."}      // 流结束
+│                  API 层 (FastAPI)                 │
 │  auth | chat | admin | market | agents | mcp     │
 │  skills | storage | billing | im_llm            │
 ├─────────────────────────────────────────────────┤
 │                业务逻辑层 (Core)                  │
 │  EngineCore | LLM Router | Node Registry         │
 │  Claw Adapters (SSE/Buffer) | OTel               │
 ├─────────────────────────────────────────────────┤
 │                 协议网关层                        │
 │  LiteLLM (model routing) | MCP Protocol         │
 ├─────────────────────────────────────────────────┤
 │                 数据层 (Storage)                  │
 │  PostgreSQL+pgvector | Redis | Meilisearch       │
 │  Qiniu/OSS Object Storage | Casdoor OAuth       │
 └─────────────────────────────────────────────────┘
 ```
---
+### 4.2 核心功能模块
-## 六、核心管道与工作流
+#### 前台 (Frontend Pages)
-### 6.1 消息处理管道（主循环）
+| 模块 | 路径 | 功能 |
 ```
 用户消息
  → 鉴权（JWT Bearer）
  → 上下文恢复（skill_ids/agent_ids/mcp_ids 跨轮继承）
  → 技能解析（显式选择 → 自动发现 → Agent 合并）
  → MCP 工具列表拉取（带缓存 TTL 120s，按 url + transport 缓存）
  → 知识库检索（RAG，BM25 + vector hybrid）
  → System Prompt 组装（AGENT_GUIDE + platform_knowledge + agent_role + skill_desc + kb_context）
  → Function Definitions 组装（skills → tools + MCP → tools + install_app）
  → LLM 调用（OpenAI 兼容协议，stream=True）
  → Tool Calls 循环（max 15 轮，每轮 tool_policy 沙箱检查）
     ├── MCP Tool → call_mcp_tool() via Anthropic SDK
     ├── Skill → _execute_skill_tool() 指令转发
     └── install_app → 安装到市场
  → 工具结果回注 → 继续 LLM 循环 → 最终回复
  → 上下文压缩（后台异步，fire-and-forget）
  → 结构化记忆抽取（实体/事实/偏好/决策/待办 五类）
  → 媒体生成（后台 daemon 线程，独立事件循环）
 ```
 ### 6.2 模型路由与 Failover 管道
 ```
 模型选择 → 解析 api_url/api_key/provider.auth_header
  → build_openai_client（httpx.Timeout + trust_env=False + auth_header 支持）
  → 首次调用失败（Exception）→ continue 下一个模型
  → 备用模型列表（order_by is_default desc × 5）
  → 成功 → break
  → 全部失败 → 返回错误消息
 ```
 ### 6.3 MCP 协议管道
 ```
 Client: mcp_client.py (官方 Anthropic SDK)
  list_mcp_tools(server) → tools/list (JSON-RPC)
    ⇢ 缓存: _TOOLS_CACHE[url] = (timestamp, tools), TTL 120s
  call_mcp_tool(server, name, arguments) → tools/call (JSON-RPC)
    ⇢ 返回: text content blocks → 拼接为字符串 → 反馈给 LLM
 传输层:
  streamable_http (默认) → streamablehttp_client()
  sse → sse_client()
 Schema 适配:
  MCP inputSchema (JSON Schema 2020-12) → _normalize_mcp_schema()
    ⇢ 展开 $ref → 处理 oneOf/anyOf → allOf 合并 → 剥离非 OpenAI 关���字
    ⇢ 转为 OpenAI function calling 兼容的 parameters
 认证:
  Authorization: Bearer {key} (默认)
  api-key: {key} (MiMo Token Plan 等自定义)
 ```
 ### 6.4 Agent 编排管道（DAG 图引擎）
 ```
 YAML 定义 → validate_graph() → topological_layers() (Kahn算法)
  → 按层并行执行 (asyncio.gather)
 节点类型:
  llm     → _build_system_prompt + LLM 调用
  local   → _execute_skill_tool (本地技能)
  external → _call_external_agent (Dify/n8n/Coze 远程)
  reduce  → 多路结果聚合
 边: 有向边定义数据流 → 拓扑排序 → 分层并行
 失败隔离: per-node on_error=halt|continue
 并发安全: 每节点独立 SessionLocal()
 预处理流水线:
  外部 Agent endpoint → 直接远程调用（跳过本地 LLM）
  Orchestrator → run_graph() → 图执行 → 聚合回答
 ```
 ### 6.5 媒体生成管道
 ```
 SSE 回复结束 → _launch_media_task_bg()
  → daemon Thread → asyncio.run(_generate_media_task)
    → 独立事件循环（不阻塞主 uvicorn 循环）
    → HTTP 调用图片/视频生成 API
    → 写入存储 → 更新 Message 记录
    → 前端轮询 → 渲染结果
 ```
 ### 6.6 上下文压缩管道
 ```
 (后台异步, fire-and-forget, 不阻塞用户响应)
 旧消息 (>20 条保护窗口外)
  → 分块 (CHUNK=30) → _summarize_via_llm()
  → chunk_summaries 合并
  → _recursive_compress() (depth≤3, budget=700 tokens)
  → _extract_structured_memory()
    实体/事实/偏好/决策/待办 五类
  → _merge_structured_memory(old, new)
  → ConversationSummary 写入 PG
 ```
 ---
 ## 七、前端架构
 ### 7.1 路由设计
 ```
 前台 (/):
  /login                      - 登录
  /chat[/:id]                 - AI 对话（核心页面，SSE 流式）
  /knowledge                  - 知识库管理
  /market                     - 应用市场（Skills/MCP/Agents）
  /token                      - Token 用量面板
  /pricing                    - 定价/会员
  /profile                    - 个人中心
  /assets[/novel/:id]         - 资产/小说
  /evolution                  - 进化仪表板
  /wechat-bot                 - 微信 Bot
  /im-bots                    - 多平台 IM Bot Hub
  /app-services               - 应用服务
 后台 (/admin):
  /admin                      - 仪表板
  /admin/users                - 用户管理
  /admin/models               - 模型管理
  /admin/skills               - 技能管理
  /admin/agents               - Agent 管理
  /admin/mcp                  - MCP 管理
  /admin/workflow             - 工作流
  /admin/market               - 市场审核
  /admin/knowledge            - 知识库管理
  /admin/code-exec            - 代码执行
  /admin/storage              - 存储管理
  /admin/developer[/tools]    - 开发者 API/工具
  /admin/automation           - 自动化任务
  /admin/settings             - 站点设置
  /admin/analytics            - 数据分析
  /admin/logs                 - 日志
  /admin/membership           - 会员管理
  /admin/payment              - 支付配置
  /admin/services             - 增值服务
  /admin/ads                  - 广告管理
  /admin/apps                 - 应用管理
 ```
 ### 7.2 核心组件
 | 组件 | 文件 | 功能 |
 |------|------|------|
-| ChatPage | front/ChatPage.tsx | SSE 流式聊天、Step 渲染、推理展示 |
+| 落地页 | `/` | 平台介绍 + Hero + 能力展示 |
-| AiProcessBlock | ChatPage.tsx 内 | 工具调用过程可视化（⏳/✅/❌） |
+| AI 对话 | `/chat` | SSE 流式对话、代码块渲染、Markdown、媒体预览 |
-| MarketPage | front/MarketPage.tsx | 应用市场网格、分类筛选 |
+| 知识库 | `/knowledge` | 文档上传、RAG 检索、向量索引管理 |
-| FrontLayout | components/layout/FrontLayout.tsx | 前台 sidebar + main 布局 |
+| 技能市场 | `/market` | Meilisearch 搜索、技能安装、上架审核 |
-| AdminLayout | components/layout/AdminLayout.tsx | 后台 sidebar + main 布局 |
+| Token 驾驶舱 | `/token` | 实时用量、消耗趋势、预警告警 |
 | 会员/定价 | `/pricing` | 套餐对比、微信支付订阅、增值付费 |
 | 个人中心 | `/profile` | 用户信息、主题设置、API Key 管理 |
 | 通知中心 | `/notifications` | 系统消息、订单通知、告警 |
 | Agent 画布 | `/agent` | 可视化编排、DAG 工作流编辑 |
 | App 服务 | `/apps` | 第三方应用集成(小说、视频等) |
-### 7.3 设计系统
+#### 后台 (Admin Pages)
 | 模块 | 路径 | 功能 |
 |------|------|------|
 | 平台驾驶舱 | `/admin` | 用户数/模型数/调用量/营收概览 |
 | 大模型库 | `/admin/models` | 供应商管理、模型 CRUD、连接测试、能力默认值配置、**自动同步 LiteLLM** |
 | Agent 管理 | `/admin/agents` | Agent 创建/编辑/状态 |
 | 技能管理 | `/admin/skills` | 技能审批、上架/下架、分类 |
 | MCP 管理 | `/admin/mcp` | MCP Server 注册/授权 |
 | 用户管理 | `/admin/users` | 用户 CRUD、角色分配 |
 | 会员管理 | `/admin/membership` | 套餐配置、续费管理 |
 | 推广系统 | `/admin/promotion` | 邀请链接、佣金结算 |
 | 计费管理 | `/admin/billing` | 充值记录、订单、退款 |
 | 应用市场 | `/admin/market` | 应用审核、产品定价、webhook |
 | 系统设置 | `/admin/settings` | 站点配置、SMS、存储 |
 | 日志审计 | `/admin/logs` | 操作日志、不可删除 |
 | Wechat Bot | `/admin/imbots` | 微信连接状态、消息历史 |
 ### 4.3 模型能力体系
 | 能力分类 | 英文标识 | 代表模型 | 用途 |
 |---------|---------|---------|------|
 | 文本对话 | text | DeepSeek-V4-Flash, MiMo-v2.5 | 通用聊天、文档生成 |
 | 推理思考 | thinking | MiMo-v2.5 | 复杂推理、逻辑分析 |
 | 视觉理解 | vision | MiMo-v2.5 | 图片识别、OCR |
 | 工具调用 | tool | MiMo-v2.5 | Function Calling |
 | 图像生成 | image | AGNES-Image-2.0-Flash | AI 绘图 |
 | 视频生成 | video | AGNES-Video-v2.0 | AI 视频生成 |
 | 语音合成 | audio | MOSS-TTSD | TTS 文字转语音 |
 | 语音识别 | asr | TeleSpeechASR | 语音转文字 |
 | OCR 识别 | ocr | DeepSeek-OCR | 文档 OCR |
 | 嵌入向量 | embedding | BAAI/bge-m3 | 文本向量化 |
 | 重排序 | rerank | BAAI/bge-reranker-v2-m3 | 检索结果重排 |
 ---
 ## 五、核心业务逻辑
 ### 5.1 AI 对话处理流 (chat.py)
 ```
-CSS 变量（global.css :root）:
+用户消息 → chat.py _send_message_core
-  --color-accent: #5B5FED
+  → capability_discovery (发现可用 MCP/Skills/Models)
-  --color-bg-primary: #F8F9FB
+  → System Prompt 组装 (知识库 + 能力清单 + 对话历史)
-  --sidebar-width: 240px
+  → LiteLLM /v1/chat/completions (master key 认证)
-  --space-xs..4xl: 4px..40px
+  → SSE 流式返回 → BufferAdapter 缓冲 → SseAdapter 推送
-  --radius-md..3xl: 8px..20px
+  → 图片生成: AGNES API → async thread → media relay → 微信推送
  → 日志: Token 用量 + 审计
 ```
-防溢出: html/body/.front-main { overflow-x: hidden }
+### 5.2 双 Claw 单引擎架构 (Dual Claw)
-响应式: @media (max-width: 1200px/768px) 断点
+
 ```
 Web Claw (SSE)                 IM Bot Claw (微信)
      │                              │
      ▼                              ▼
 SseAdapter                      BufferAdapter
      │                              │
      └──────────┬───────────────────┘
                 ▼
        EngineCore._send_message_core (唯一引擎)
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
  LLM Router  MCP SDK  Capability Discovery
 ```
 **关键设计原则**:
 - 能力发现 `capability_discovery.py` Web/IM 共用
 - MCP 命名 `mcp__{safe(name,30)}__{safe(tool,50)}__{idx}` 统一
 - `tests/test_dual_claw.py` R-DUAL 集成哨兵
 ### 5.3 模型同步机制 (#965 LiteLLM Sync)
 ```
 管理员 UI "添加模型" → models.py create_model()
  → PostgreSQL aiflow.AIModel 写入 ✅
  → threading.Thread → LiteLLM REST API /model/new ✅
  → LiteLLM litellm DB 热加载 ✅
  → 用户立即可用 ✅
 STORE_MODEL_IN_DB=True (docker-compose)
 ```
 ### 5.4 媒体生成与中转 (#967 media_relay)
 ```
 用户请求 "生成图片" → chat.py 检测 intent
  → AGNES API /v1/images/generations
  → SiliconFlow S3 存储 → 临时 URL (24h)
  → media/relay (httpx stream + domain whitelist)
  → WeChat / Web SSE 内联渲染
 ```
 ### 5.5 安全纵深防御
 ```
 第一层: Nginx 限流
  - API: 30 r/s | Admin: 5 r/s | Login: 1 r/s
 第二层: 扫描器拦截
  - Path 14 类 (.git/.env/wp-login/etc) → 444
  - UA 20 类 (zgrab/nmap/gobuster/etc) → 444
  - Client SDK (curl/wget/python-requests) → 444
 第三层: 自动黑名单
  - /app/backend/nginx/block_ip.py
  - 5min cron + 24h TTL
  - 基于 4xx 错误率和 UA 模式
 第四层: JWT + Casdoor 认证
  - JWT Bearer Token
  - role-based 路由 (super_admin/admin/user)
 ```
 ---
-## 八、安全设计
+## 六、设计系统 (qihu-design-system)
-### 8.1 认证
+### 6.1 设计理念
- JWT Bearer Token 认证（FastAPI HTTPBearer）
+**温暖科技感 + 极简主义** (Warm Tech Minimalism)。护眼雾白底，靛蓝 `#5B5FED` 为唯一品牌色。
 - Casdoor OAuth2/OIDC 统一认证（可选）
 - Token 前端存内存，401/403 清 token 跳 /login
-### 8.2 授权
+### 6.2 技术实现
- 前台: 用户级（需登录）
+| 维度 | 值 |
- 后台: 管理员级（role=admin）
+|------|-----|
- API Key: 支持 per-model key 覆盖 provider key
+| 主品牌色 | `#5B5FED` (indigo) |
 | 暗态品牌色 | `#8289F5` |
 | 签名渐变 | indigo → violet(#8B5CF6) → fuchsia(#D946EF) |
 | 字体 | Inter (正文/标题) + JetBrains Mono (代码) |
 | CSS 框架 | Tailwind v4.3 (@tailwindcss/vite) |
 | 主题 | light / dark / system 三态，Zustand persist + matchMedia |
 | 组件库 | 53 modules，CSS 55KB / JS 244KB / 1.36s build |
-### 8.3 工具调用沙箱
+### 6.3 组件体系
 ```yaml
 ui: Button(6 variants) | Badge(6v) | Input | Card(6v+cardSurface)
 canvas: GenUiCard(7 themes) | StatusRing(6 states) | ChatComposer(glass)
 layout: AppShell(NavRail+drawer+skip-link) | ThemeToggle | ReaderTabs
 ```
 _check_tool_policy() 三层防护:
  1. 白名单: agent 只允许调特定 skill_ids + mcp_ids
  2. 预算: max_calls_per_conversation 上限
  3. 每轮上限: per_round_cap
-代码执行: 独立 executor 容器沙箱
+### 6.4 设计铁律
-密钥管理: credential.py 加解密存储
+
-```
+- ❌ 禁硬编码 `bg-blue-*`/`bg-sky-*`/`bg-indigo-600`
 - ✅ GenUi 走 primary 语义 token
 - ✅ 变体映射必须 `Record<Variant, string>` + `cn()`，禁 `bg-primary-${w}`
 - ✅ 暗态 `.dark` 双写；玻璃/辉光统一 `.glass`/`.glow`
 - ✅ 动效尊重 `prefers-reduced-motion`
 - ✅ 条纹: `--chat-accent` / `--r-sm|md|lg` / `--chat-ease cubic-bezier(0.2,0.8,0.2,1)` / `--chat-duration 200ms`
 ---
-## 九、运维架构
+## 七、运维与可靠性
-### 9.1 CI/CD
+### 7.1 Safe-Align 工作流
 ```
-Git push → pre-push hook (.git/hooks/pre-push)
+① 备份: docker commit → backup 镜像 + git tag + bundle + PG dump
-  → 容器内 backend pytest (28 用例)
+② 拷贝: 仅 git-tracked 源文件 容器→宿主 git
-  → 容器内 frontend vitest (2 文件, 15 用例)
+③ 提交: git add + commit (不 push)
-  → 全绿 → push 放行
+④ 校验: docker restart + 验证 + docker commit → with-deps
  → 失败 → block
 部署:
  docker cp 容器文件 → 宿主 Git
  → git add -A + commit
  → docker commit → qihuaiflow:with-deps (新镜像)
  → docker compose up -d --force-recreate
 ```
-### 9.2 健康检查
+**真相源**: 容器 (image := container := git)
-```
+### 7.2 监控
 /health          → 200 {status: "ok"}     (liveness)
 前端 :8080       → 200 HTML               (SPA)
 后端 :18080/docs → 200 Swagger UI
 容器: docker restart → < 20s 恢复
 ```
-### 9.3 监控栈
+- Grafana 双 Claw 对比看板 `uid: qihuaiflow-dual-claw-876`
 - OTel traces + metrics (alloy → Prometheus)
 - 日志级别: INFO (生产) / DEBUG (开发)
-```
+### 7.3 备份策略
-Prometheus (scrape) ← node-exporter (host) + Alloy (logs)
+
-Grafana (visualize) ← Prometheus datasource
+- 每 6h 自动备份 (cron)
-应用日志: Python logging → docker logs / Alloy 采集
+- PG dump (不用 --ssl=0 否则 0 bytes)
-```
+- Docker image snapshot: `qihuaiflow:backup-*{TS}`
 - nginx logrotate 每日轮转
 ---
-## 十、市场竞争分析
+## 八、迭代路线
-### 10.1 护城河
+### 8.1 已完成 (2026-08-11)
-| 护城河 | 具体实现 | 壁垒强度 |
+| 编号 | 描述 | commit |
-|--------|---------|---------|
+|------|------|--------|
-| **多模型协议适配层** | OpenAI/Anthropic/Token Plan 三种认证头、MCP Schema → OpenAI 转换 | 🔴 高 |
+| #957 | Nginx server 级 root 修复 | 53bbbf3 |
-| **Skill 全生命周期** | 发布→审核→上架→安装→执行→进化，闭环 | 🔴 高 |
+| #959 | Index.html no-store cache | 45b6939 |
-| **Agent DAG 编排** | 拓扑排序+分层并行+失败隔离+外部 Agent 远程调用 | 🟡 中 |
+| #961 | React hydration error fix | 4cf910e |
-| **工具调��标准化** | AGENT_GUIDE + tool_policy 沙箱 + 15 轮 loop + 错误自修正 | 🟡 中 |
+| #962 | Global ErrorBoundary | 420e0f6 |
-| **PG 统一数据层** | 主库+向量+Casdoor 同集群 pgvector，混合检索零延迟 | 🟡 中 |
+| #963 | safeLazy chunk load fallback | 679f23f |
-| **IM Bot 多平台** | 统一消息网关，微信/企业微信/飞书/QQ | 🟢 低 |
+| #964 | React hooks rules fix (#321) | fa38d2c |
-| **安全沙箱** | Tool Policy 白名单+预算+代码执行容器隔离 | 🟡 中 |
+| #965 | LiteLLM platform-model sync | fd84fec |
 | #966 | Container restart loop fix | 75be24c |
 | #967 | media_relay endpoint impl | 54b444b |
-### 10.2 竞品对比
+### 8.2 下一步候选
-| 维度 | 七虎AI | Dify | Coze | 扣子 | FastGPT |
+| 优先级 | 项目 | 工作量 |
-|------|--------|------|------|------|---------|
+|--------|------|--------|
-| 模型聚合 | ✅ 手动 failover | ✅ | ✅ | ✅ | ✅ |
+| 🟢 P0 | 企业微信官方 Bot API 接入 | 3 天 |
-| Skill 市场 | ✅ 上架-安装-进化 | ❌ | ❌ (Plugin) | ❌ (Plugin) | ❌ |
+| 🟢 P1 | 后端核心模块单测补全 (165→300+) | 3 天 |
-| MCP 协议 | ✅ 官方 SDK | ✅ | ❌ | ❌ | ❌ |
+| 🟡 P1 | Alloy traces 配置 bake to image | 1 天 |
-| Agent DAG | ✅ 图引擎 | ✅ 工作流 | ✅ 工作流 | ✅ 工作流 | ❌ 简单 |
+| 🟡 P1 | 多租户 PG RLS 隔离 | 5 天 |
-| IM Bot | ✅ 多平台 | ❌ | ❌ | ✅ 飞书 | ❌ |
+| ⚪ P2 | 语音/视频流式响应 | 5 天 |
-| PG 全栈 | ✅ PG18 | ⚠️ MySQL | ? | ? | ✅ PG |
+| ⚪ P2 | Agent 画布可视化编排 | 7 天 |
 | Auth | ✅ Casdoor+JWT | ✅ | ✅ | ✅ | ✅ |
-### 10.3 扩展能力
+### 8.3 长期方向
-| 扩展方向 | 当前能力 | 增长空间 |
+1. **模型 → 智能体**: 从简单的模型调用升级到自主 Agent + 多步推理
-|---------|---------|---------|
+2. **单机 → 集群**: Docker Compose → Kubernetes + Helm
-| 模型厂商 | 4 家 | 新增厂商只需配 ModelProvider |
+3. **中国市场 → 国际化**: 多语言 + 多区域部署
-| Skill 类型 | 14 场景分类 | 支持自定义执行器（非纯 LLM 转发） |
+4. **技能市场 → 开放生态**: 第三方开发者平台 + 收入分成
-| MCP 服务 | 任意 MCP Server | MCP Registry 对接 |
+5. **个人微信 → 企业微信**: 合规化 IM Bot 渠道
 | Agent | Dify/n8n/Coze + 自研 DAG | CrewAI/LangGraph 集成 |
 | 前端渠道 | Web Chat + IM Bot | API/Webhook/SDK |
 | 计费 | Token + 会员 | 按 Skill/MCP 调用计费 |
 ---
-## 十一、迭代路线图
+## 九、附录
-### 已完成
+### 9.1 服务器信息
- [x] PostgreSQL 迁移（MySQL → PG18 + pgvector）
+| 项 | 值 |
- [x] SSE 四类事件（reasoning/delta/step/done）
+|------|-----|
- [x] MCP 协议标准化（官方 SDK，Schema 转换）
+| IP | 210.16.161.218 |
- [x] Agent DAG 编排引擎 + YAML workflow
+| OS | Ubuntu 24.04 |
- [x] 工具调用标准化（AGENT_GUIDE + install_app 优化 + max_rounds 15 + MCP 命名）
+| 公网地址 | https://ai.qihuyun.com |
- [x] 模型 Failover + 事件循环防冻（#812）
+| 后台地址 | https://ai.qihuyun.com/admin |
- [x] Token Plan 适配（MiMo custom auth_header）
+| 默认账户 | admin / admin123 |
- [x] 前端 Step 渲染增强（⏳/✅/❌ 状态）
+| Git | http://git.qihuyun.com/qyyfw/qihuaiflow |
 - [x] 横向溢出防护（overflow-x: hidden 三层）
 - [x] 知识库 KG 构建
 - [x] 多平台 IM Bot Hub
 - [x] Prometheus+Grafana 监控栈
-### 进行中
+### 9.2 关键文件路径
- [ ] Skill 真实执行器（非 LLM 转发模拟）
+| 文件 | 容器路径 |
- [ ] 多 Agent 协作（Supervisor 模式）
+|------|---------|
- [ ] API/OpenAPI 对外接口
+| 后端入口 | `/app/backend/python/main.py` |
- [ ] 技能 SDK 发布工具
+| AI 对话 | `/app/backend/python/app/api/chat.py` |
 | LLM 网关 | `/app/backend/python/app/core/llm_router.py` |
 | 双 Claw | `/app/backend/python/app/core/claw_adapters.py` |
 | 同步服务 | `/app/backend/python/app/core/litellm_sync.py` |
 | 前端入口 | `/app/frontend/src/main.tsx` |
 | Nginx 配置 | `/etc/nginx/conf.d/aiflow.conf` |
 | LiteLLM 配置 | `/app/config.yaml` (litellm 容器) |
-### 计划中
+### 9.3 调试经验
- [ ] LiteLLM 集成（统一模型路由+成本追踪）
+| 问题 | 解决方案 |
- [ ] 流式 Token 计费（精确到字符级）
+|------|---------|
- [ ] LangGraph 工作流引擎
+| 容器重启循环 | docker stop → docker cp 修复文件 → docker start |
- [ ] 向量混合检索增强（BM25 + dense + sparse）
+| React #321 hooks error | useState 必须在组件函数内，不能模块顶层 |
- [ ] 前端暗色模式
+| Chrome 缓存旧 HTML | index.html 加 Cache-Control: no-store |
- [ ] 多语言（i18n）
+| nginx 调测 444 | curl 用 -A 'Mozilla/5.0' 避免被 P1-2 拦截 |
- [ ] 移动端适配
+| Docker tag 短ID 报错 | 必须用完整 sha256: 格式 ID |
-
+| SSH paramiko 掉线 | get_ssh() 3次重试 + 指数退避 |
 ---
 > **文档维护规则**: 每次系统重大迭代后，更新本文档对应章节并变更版本号。
 > **上传位置**: Gitea 仓库 `qihuaiflow/docs/ARCHITECTURE.md`