TFRobotServer

基于 TFRobot 框架的「数字员工」服务端，提供 RESTful API 接口。

简介

TFRobotServer 是对 TFRobot 框架的 FastAPI 封装，将其能力以服务形式对外提供。通过灵活的 API 接口，可以实现对 TFRobot 的配置调整和动态管理，并支持 Kubernetes 集群部署。

核心目标

服务化封装：将 TFRobot 的功能封装为 RESTful API
动态配置：通过 API 实时调整 Robot 配置
云原生部署：支持 Kubernetes 部署，每个 Pod 提供独立服务
可观测性：内置监控、日志记录和仪表板能力
异步任务：通过 Celery 提供高并发任务处理能力

核心特性

单线程执行模型

TFRobotServer 采用单线程模式运行，这是由以下设计决定：

配置依赖：TFRobot 配置存储在文件系统，单进程确保配置一致性
应用场景：「数字员工」场景无需高并发，单个员工专注处理任务
资源管理：避免多进程带来的资源竞争和状态同步问题

对于有限的并发需求，使用 FastAPI 的异步模式（async/await）即可满足。

分层架构

┌─────────────────────────────────────────────────┐
│                   API Layer                      │
│        (RESTful API - FastAPI)                  │
└─────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│                 Services Layer                   │
│         (业务逻辑 - RobotFactory, Admin)         │
└─────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│              Dependencies Layer                  │
│      (依赖注入 - TFSContainer + Providers)       │
└─────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│           Infrastructure Layer                   │
│    (Database, Redis, Celery, TFRobot Core)       │
└─────────────────────────────────────────────────┘

OpenTelemetry 集成

完整的调用链追踪，可接入 Grafana 等监控系统。

技术栈

类别	技术
Web 框架	FastAPI + Uvicorn
数据验证	Pydantic V2
ORM	SQLAlchemy 2.0 (异步)
依赖注入	dependency-injector
任务队列	Celery + RabbitMQ
数据库	PostgreSQL + Redis
追踪	OpenTelemetry
文档	MkDocs + Material
接口文档	Apifox

快速开始

环境要求

Python 3.11+
Poetry
Kubernetes (可选，用于生产部署)
kubectl CLI (可选)

初始化开发环境

# 1. 安装依赖并初始化 alembic
make init

# 2. 重置 PostgreSQL 数据库（需要 k8s）
make reset_postgresql

# 3. 重置 Redis 并重建索引（需要 k8s）
make reset_redis

# 4. 启动开发服务器
poetry run uvicorn tfrobotserver.main:app --host 0.0.0.0 --port 8000 --reload

运行测试

# 单元测试
make test-unit

# 集成测试
make integration_tests

# 完整测试（含覆盖率）
make test-coverage

文档导航

API 接口

详细的 API 接口文档请查阅 Apifox。

设计文档： - Chat API 设计 - Admin API 设计 - Robot Factory API 设计

服务层

基础设施

设计约定

分页从 0 开始

所有分页接口的页码从 0 开始（而非 1）。

环境变量前缀

配置项使用 TFS_ 前缀，例如： - TFS_USERNAME - TFS_PROFILE

数据库 Schema

所有表使用 tfrserver schema。

索引定义

使用 Index() 类定义索引，而非 __table_args__（因为基类已占用）。

开发指南

代码格式化

make format  # Ruff 格式化和导入排序
make lint    # MyPy 和 Ruff 检查

数据库迁移

make upgrade_postgresql  # 自动生成并应用迁移

常用命令

# 查看可用命令
make help

# 重置 MinIO（需要 mc CLI 和 jq）
make reset_minio

架构说明

与 TFRobot 的关系

┌────────────────────────────────────────────┐
│         TFRobotServer (本项目)             │
│  ┌──────────────────────────────────────┐ │
│  │   FastAPI Web 服务 (RESTful API)    │ │
│  └──────────────────────────────────────┘ │
│  ┌──────────────────────────────────────┐ │
│  │   Celery 任务队列                    │ │
│  └──────────────────────────────────────┘ │
└────────────────────────────────────────────┘
                   ↓ 调用
┌────────────────────────────────────────────┐
│         TFRobot 核心框架                   │
│  (Chain/Memory/Tool/Drive/Neural)         │
└────────────────────────────────────────────┘

部署架构

                    Kubernetes Cluster
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    ┌───▼────┐        ┌───▼────┐        ┌───▼────┐
    │  Pod 1 │        │  Pod 2 │        │  Pod N │
    │ (员工A) │        │ (员工B) │        │ (员工N) │
    └────────┘        └────────┘        └────────┘
         │                  │                  │
         └──────────────────┼──────────────────┘
                            │
              ┌─────────────▼─────────────┐
              │   PostgreSQL + Redis      │
              │   RabbitMQ + MinIO        │
              └───────────────────────────┘

常见问题

Q: 为什么采用单线程模式？

A: TFRobot 配置依赖文件系统，多进程会导致配置不一致。数字员工场景也无需高并发，异步模式已能满足有限并发需求。

Q: 如何扩展并发能力？

A: 通过 Kubernetes 水平扩展 Pod 数量，每个 Pod 独立运行一个「数字员工」。

Q: API 文档在哪里？

A: 详细接口文档在 Apifox 中维护，设计文档说明接口的设计思路和使用场景。

版本信息

当前版本：0.1.1-rc2