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 安装（推荐，适合客户站点）

pip install baibai-framework

可选功能依赖：

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 步：安装框架

pip install "baibai-framework[ai]"

第 2 步：创建站点

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 步：配置密钥

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

第 4 步：启动

python app.py

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

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

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

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

重启 python app.py 即可生效。

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

# 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)

---

五·五、升级与维护

检查当前版本

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

升级到最新版本

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

升级到指定版本

pip install baibai-framework==0.2.0

查看可用版本

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

数据备份

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

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

卸载

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

---

六、site.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）

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 开关

调试

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

# 运行测试
python test_framework.py

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

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

# 一键构建（自动：前端构建 → 复制 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 — pip 安装包
• baibai-platform — 数字分身平台控制平面
• site-baibai — 第一个实例站点
• 数字分身平台架构方案: baibai/数字分身平台架构方案_d5b4a17b.md