# BaiBai Framework

AI 数字分身站点框架 — 从 Monorepo 到「框架即依赖」的可插拔架构

> 版本: v0.1.1 | Python >= 3.11 | Flask 3.1 | MIT License

---

## 一、项目概述

baibai-framework 是数字分身平台三层架构中的**能力层**，为每个数字分身实例站点提供标准化的运行时骨架。站点只需创建一个 `site.json` 配置文件和两行入口代码，即可获得完整的 AI 数字分身功能。

### 三层架构中的角色

```
baibai-platform (控制平面)  →  管理多个实例、接收同步数据、A2A 路由代理
        ↕ REST API + Sync
baibai-framework (能力层)    →  提供 create_app() 工厂、插件体系、PlatformSync
        ↓ 被依赖
site-baibai / site-* (实例)  →  独立部署的站点，拥有独立 SQLite 数据库
```

---

## 二、架构设计

### 核心模块

| 模块 | 路径 | 职责 |
|------|------|------|
| **app_factory** | `core/app_factory.py` | `create_app()` 工厂函数，组装 Flask 应用 |
| **site_loader** | `core/site_loader.py` | 从 `site.json` 加载配置，环境变量覆盖 |
| **database** | `core/database.py` | SQLite WAL 模式数据库层，表结构初始化 |
| **platform_sync** | `core/platform_sync.py` | 实例侧数据同步客户端，定时向平台上报 |
| **plugin_registry** | `plugins/` | 可插拔架构核心，按 features 开关动态挂载 Blueprint |

### 插件体系

所有功能通过 `PluginRegistry` 统一管理。`site.json` 的 `features` 字段控制启用状态：

```
site.json features
       │
       ▼
PluginRegistry.register_all_plugins()
       │
       ├── 核心 (默认启用): admin_dashboard, analytics, seo, blog, chat, contact, booking,
       │                   voice, projects, skills, resources, profile, public_api
       ├── 管理后台: personal_assistant, knowledge_chat, chat_admin
       ├── 三方集成: lark, openclaw, bijinote, uumit, a2a
       ├── 内容同步: content_sync, sync_skills, sync_projects
       └── 预留插槽: wecom, dingtalk
       │
       ▼
registry.init_app(app) → 注册 Blueprint + 验证依赖
```

### 应用启动流程

```
1. create_app(site_name="baibai")
2. load_site_config() → 读取 site.json + .env 覆盖
3. 创建 Flask 实例，配置 CORS + 速率限制
4. 注册 SPA 回退路由
5. 注册健康检查 /api/health
6. 注册平台桥接端点 (platform_bridge)
7. 根据 features → PluginRegistry.init_app() 注册 Blueprint
8. 启动 PlatformSync (实例→平台数据同步)
9. 返回配置好的 Flask app
```

---

## 三、技术栈

| 层 | 技术 | 版本 | 用途 |
|---|------|------|------|
| 后端 | Python | 3.11+ | 运行时 |
| Web | Flask | 3.1+ | Web 框架 |
| 数据库 | SQLite | WAL 模式 | 实例本地数据库 |
| 定时任务 | APScheduler | 3.10+ | 同步调度 |
| AI | openai (可选) | 1.30+ | DeepSeek API 调用 |
| TTS | edge-tts (可选) | 6.1+ | 语音合成 |
| 前端 | React + Vite + Tailwind | 18 / 6 / 3 | SPA 构建 |

---

## 四、安装

### 方式一：从 PyPI 安装（推荐，适合客户站点）

```bash
pip install baibai-framework
```

可选功能依赖：

```bash
pip install "baibai-framework[ai]"      # 启用 AI 对话功能
pip install "baibai-framework[voice]"   # 启用 AI 语音通话
pip install "baibai-framework[all]"     # 安装所有可选功能
```

### 方式二：写入 requirements.txt

```
# requirements.txt
baibai-framework>=0.1.0
```

---

## 五、快速开始（3 分钟建站）

### 第 1 步：安装框架

```bash
pip install "baibai-framework[ai]"
```

### 第 2 步：创建站点

```bash
create-baibai-site mysite --domain mysite.com --brand "我的品牌" --port 3001
```

这会在当前目录生成 `site-mysite/`，结构如下：

```
site-mysite/
├── site.json          # 站点配置（品牌、功能开关、AI 配置）
├── .env.example       # 环境变量模板
├── app.py             # 入口文件（仅两行）
├── seed.py            # 内容种子脚本
├── requirements.txt   # 依赖声明
└── content/           # 博客、数据库等运行时数据
```

### 第 3 步：配置密钥

```bash
cd site-mysite
cp .env.example .env
# 编辑 .env，填入以下必填项:
#   DEEPSEEK_API_KEY=sk-xxx   (AI 对话功能必须)
#   ADMIN_PASSWORD=yourpass   (管理后台密码)
```

### 第 4 步：启动

```bash
python app.py
```

访问 `http://localhost:3001` 查看站点，`http://localhost:3001/admin` 进入管理后台。

### 第 5 步：自定义配置（可选）

编辑 `site.json` 按需调整品牌颜色、功能开关、AI 模型等：

```json
{
  "brand": { "name": "我的品牌", "primaryColor": "#3b82f6" },
  "features": { "voice": true, "lark": false }
}
```

重启 `python app.py` 即可生效。

### 手动创建入口（不用 CLI 时）

```python
# app.py — 仅两行
from baibai_framework import create_app
app = create_app(site_name="mysite")

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=3001)
```

---

## 五·五、升级与维护

### 检查当前版本

```bash
pip show baibai-framework
# 访问: http://localhost:3001/api/health
```

### 升级到最新版本

```bash
pip install --upgrade baibai-framework
python app.py   # 重启即可，数据库会自动迁移
```

### 升级到指定版本

```bash
pip install baibai-framework==0.2.0
```

### 查看可用版本

👉 https://pypi.org/project/baibai-framework/#history

### 数据备份

框架内置自动备份（每天凌晨 3:00，保田 7 份）。如需手动备份：

```bash
# 备份数据库
cp content/data/mysite.db content/data/mysite.db.bak
```

### 卸载

```bash
pip uninstall baibai-framework
# 站点数据（content/）不会被删除，可手动清理
```

---

## 六、site.json 配置参考

```json
{
  "name": "your-site",
  "domain": "your-domain.com",

  "brand": {
    "logo": "",
    "name": "你的品牌名称",
    "primaryColor": "#3b82f6"
  },

  "ai": {
    "model": "deepseek-v4-pro",
    "baseUrl": "https://api.deepseek.com",
    "systemPrompt": "你是...",
    "apiKey": ""              // 从环境变量 DEEPSEEK_API_KEY 注入
  },

  "server": {
    "port": 3001,
    "debug": false,
    "corsOrigins": ["http://localhost:5173"]
  },

  "admin": {
    "password": "",           // ADMIN_PASSWORD 环境变量注入
    "demoPassword": "",       // DEMO_PASSWORD 环境变量注入
    "demoTokenPrefix": "demo_"
  },

  "features": {
    "blog": true,             // 博客系统
    "chat": true,             // AI 对话
    "contact": true,          // 咨询/预约
    "booking": true,          // 预约系统
    "voice": false,           // AI 语音通话
    "projects": true,         // 项目展示
    "skills": true,           // 技能矩阵
    "resources": true,        // 资源下载
    "lark": false,            // 飞书集成
    "openclaw": false,        // OpenClaw 同步
    "bijinote": false,        // Get笔记同步
    "uumit": false,           // UUMit A2A
    "content_sync": false,    // 内容同步
    "a2a": true,              // A2A 协议
    "adminDashboard": true    // 管理后台
  },

  "theme": {
    "primaryColor": "#3b82f6",
    "darkMode": "auto",
    "borderRadius": "md"
  },

  "platform": {
    "sync": {
      "enabled": true,
      "platformUrl": "http://localhost:4000",
      "syncToken": "",
      "intervals": {
        "heartbeat": 5,       // 心跳: 5分钟
        "metrics": 30,        // 指标: 30分钟
        "a2a_log": 30,        // A2A日志: 30分钟
        "chat_stats": 60,     // 对话统计: 1小时
        "error_report": 60    // 错误报告: 1小时
      },
      "retryMaxAttempts": 3,
      "retryBackoffSeconds": [30, 120, 600]
    }
  },

  "paths": {
    "db": null,               // 自动计算: content/data/{name}.db
    "content": null,          // 自动计算: content/
    "blog": null,             // 自动计算: content/blog/
    "dist": null              // 自动查找，优先级: frontend/dist/ → dist/ → 包内内置
  },

  "corsOrigins": ["https://your-domain.com"]
}
```

### 环境变量（.env）

```bash
DEEPSEEK_API_KEY=sk-xxx       # DeepSeek API 密钥
ADMIN_PASSWORD=xxx            # 管理员密码
DEMO_PASSWORD=demo2026!       # 演示模式密码
LARK_APP_ID=xxx               # 飞书应用 ID
LARK_APP_SECRET=xxx           # 飞书应用密钥
PLATFORM_URL=http://localhost:4000
PLATFORM_SYNC_TOKEN=sk_sync_xxx
```

---

## 七、核心模块详解

### 7.1 site_loader — 配置加载

- 从 `site.json` 加载完整站点配置
- 环境变量自动覆盖敏感字段（API Key、密码等）
- 自动计算路径、推导功能开关（如 lark.enabled = bool(app_id and app_secret)）
- 输出 `SiteConfig` 数据类，包含所有子配置

### 7.2 PluginRegistry — 插件系统

- 26 个插件定义在 `plugins/definitions.py`
- 支持依赖验证（如 contact 依赖 blog）
- 支持预留插槽（wecom, dingtalk 暂无实现）
- 按 `site.json.features` 开关动态挂载 Blueprint

### 7.3 PlatformSync — 数据同步客户端

- 实例侧主动向 baibai-platform 上报数据
- 5 种同步类型: heartbeat / metrics / a2a_log / chat_stats / error_report
- APScheduler 定时调度，间隔可配置
- 容错: 失败缓存到本地 `pending_sync` 表，网络恢复后自动追赶
- 重试: 3 次退避 (30s / 120s / 600s)

### 7.4 A2A Server — Google A2A 协议

- 自动生成 `/.well-known/agent.json` Agent Card
- 处理 JSON-RPC: `tasks/send`, `tasks/get`, `tasks/cancel`, `tasks/sendSubscribe`
- 从 site.json features 映射 skills 列表

### 7.5 app_factory — 应用工厂

- `create_app(site_name, site_config, config_override)` 一站式创建
- 自动注册: SPA 回退、健康检查、平台桥接
- 可选注册: 按功能开关挂载 Blueprint
- 可选启动: PlatformSync 后台线程

---

## 八、功能插件清单

| 插件 Key | 名称 | 类别 | 后端 Blueprint | 默认启用 |
|----------|------|------|---------------|---------|
| `blog` | 博客系统 | core | `features/blog.py` | true |
| `chat` | AI 对话 | core | `features/chat.py` | true |
| `contact` | 咨询/预约 | core | `features/contact.py` | true |
| `booking` | 预约系统 | core | 同上（共用 contact BP） | true |
| `voice` | AI 语音通话 | core | `features/voice.py` | false |
| `projects` | 项目展示 | core | `features/projects.py` | true |
| `skills` | 技能矩阵 | core | `features/skills.py` | true |
| `resources` | 资源下载 | core | `features/resources.py` | true |
| `profile` | 个人资料 | core | `features/profile.py` | true |
| `public_api` | 公共 API | core | `features/public_api.py` | true |
| `admin_dashboard` | 管理后台 | admin | `features/admin.py` | true |
| `personal_assistant` | 个人助手 | admin | `integrations/me/` | true |
| `knowledge_chat` | 知识库对话 | admin | 同上（共用 ME BP） | true |
| `chat_admin` | 管理端对话 | admin | `features/chat_admin.py` | true |
| `a2a` | A2A 协议 | integration | `features/a2a_server.py` | true |
| `analytics` | 分析追踪 | core | `features/analytics.py` | true |
| `seo` | SEO 优化 | core | `features/seo.py` | true |
| `lark` | 飞书集成 | integration | `integrations/lark/` | false |
| `openclaw` | OpenClaw 同步 | sync | `integrations/openclaw/` | false |
| `bijinote` | Get笔记 | sync | `integrations/bijinote/` | false |
| `uumit` | UUMit A2A | integration | `integrations/uumit/` | false |
| `content_sync` | 内容同步 | sync | `integrations/sync/` | false |
| `sync_skills` | 技能同步 | sync | 同上（共用 sync BP） | false |
| `sync_projects` | 项目同步 | sync | 同上（共用 sync BP） | false |
| `wecom` | 企业微信 | integration | (预留) | false |
| `dingtalk` | 钉钉 | integration | (预留) | false |

> 注: booking/knowledge_chat/sync_skills/sync_projects 与对应主插件共享 Blueprint，通过单独注册支持独立开关控制。
> 注: analytics、seo、public_api、chat_admin 为后端专用插件，无前端路由。

---

## 九、当前进度

| 模块 | 状态 | 说明 |
|------|------|------|
| app_factory | **完成** | create_app() 工厂函数 |
| site_loader | **完成** | 配置加载 + 环境变量覆盖 |
| PluginRegistry | **完成** | 26 插件注册 + 依赖验证 |
| blog feature | **完成** | Markdown 博客 + RSS |
| chat feature | **完成** | SSE 流式 AI 对话 |
| contact feature | **完成** | 咨询 + 预约 |
| admin feature | **完成** | 管理后台 + 演示模式 |
| analytics + seo | **完成** | 页面追踪 + SEO 元数据 |
| a2a_server | **完成** | Google A2A 协议服务端 |
| platform_bridge | **完成** | 平台指令接收端点 |
| platform_sync | **完成** | 5 类数据同步 + 容错 |
| lark integration | **完成** | 飞书 OAuth + 文档 + 通讯录 + 审批 + 多维表 + 云盘 |
| openclaw integration | **完成** | 工作快照同步 + 洞察生成 |
| bijinote integration | **完成** | Get笔记同步 + 语义搜索 |
| uumit integration | **完成** | A2A 商业拓展 |
| content_sync | **完成** | 三源同步 (SkillHub/ClawHub/GitHub) |
| site-template | **完成** | 站点脚手架模板（内置于 pip 包） |
| create-site CLI | **完成** | 命令行站点生成工具（`create-baibai-site`） |
| PyPI 包发布 | **完成** | `pip install baibai-framework` |
| npm 包发布 | 待完善 | 前端框架包独立发布 |

---

## 十、开发指南

### 项目结构

```
baibai-framework/
├── backend/
│   └── baibai_framework/
│       ├── __init__.py          # 公开 API: create_app, SiteConfig
│       ├── app_factory.py       # 应用工厂
│       ├── core/                # 核心模块
│       │   ├── site_loader.py   # 配置加载
│       │   ├── database.py      # SQLite 数据库
│       │   └── platform_sync.py # 数据同步客户端
│       ├── features/            # 功能 Blueprint
│       │   ├── admin.py         # 管理后台
│       │   ├── blog.py          # 博客
│       │   ├── chat.py          # AI 对话
│       │   ├── contact.py       # 咨询/预约
│       │   ├── analytics.py     # 分析追踪
│       │   ├── seo.py           # SEO
│       │   ├── a2a_server.py    # A2A 协议
│       │   └── platform_bridge.py
│       ├── integrations/        # 第三方集成
│       │   ├── lark/            # 飞书
│       │   ├── openclaw/        # OpenClaw
│       │   ├── uumit/           # UUMit
│       │   ├── bijinote/        # Get笔记
│       │   ├── sync/            # 内容同步
│       │   └── me/              # 个人助手
│       ├── plugins/             # 插件系统
│       │   ├── __init__.py      # PluginDef, PluginRegistry
│       │   └── definitions.py   # 26 插件定义
│       └── cli/                 # CLI 工具
│           ├── create_site.py   # create-baibai-site 入口
│           └── templates/       # 站点模板（构建时生成）
├── frontend/                    # React 组件库源码
├── scripts/
│   └── build_package.py         # 一键构建发布脚本
├── site-template/               # 站点脚手架模板
├── pyproject.toml               # Python 包配置
├── MANIFEST.in                  # sdist 打包规则
├── site.json.example            # 配置示例
└── test_framework.py            # 框架测试
```

### 添加新插件

1. 在 `features/` 或 `integrations/` 下实现 Blueprint
2. 在 `plugins/definitions.py` 注册 PluginDef
3. 声明依赖关系 (dependencies)
4. 在 `site.json.example` 添加对应 feature 开关

### 调试

```bash
# 安装开发模式
pip install -e backend/

# 运行测试
python test_framework.py

# 在 site-baibai 中验证
cd ../site-baibai && python app.py
```

### 构建与发布（框架开发者专用）

```bash
# 一键构建（自动：前端构建 → 复制 dist 到包内 → 复制模板 → 生成 wheel + sdist）
python scripts/build_package.py

# 跳过前端重新构建（仅重打 Python 包）
python scripts/build_package.py --skip-frontend

# 构建并上传到 PyPI
python scripts/build_package.py --upload pypi
```

### 端口规划

| 组件 | 端口 | 说明 |
|------|------|------|
| site-baibai 后端 | 3001 | 实例后端 |
| site-baibai 前端 | 5173 | Vite 开发服务器 |
| baibai-platform 后端 | 4000 | 平台后端 |
| baibai-platform 前端 | 4001 | 平台前端 |

---

## 十一、相关项目

- **[baibai-framework on PyPI](https://pypi.org/project/baibai-framework/)** — pip 安装包
- **[baibai-platform](https://github.com/your-org/baibai-platform)** — 数字分身平台控制平面
- **[site-baibai](https://github.com/your-org/site-baibai)** — 第一个实例站点
- 数字分身平台架构方案: `baibai/数字分身平台架构方案_d5b4a17b.md`
