机器人端 (Raspberry Pi) · 云端后端 (FastAPI) · Web 控制台 (Vue 3)
MQTT 遥测控制 · WebSocket 实时流 · 25 个可插拔子模块
| 特性 | 说明 | |
|---|---|---|
| 🧩 | 模块化架构 | 25 个可插拔子模块,JSON 配置驱动启停与热重载 |
| 📡 | 事件驱动 | EventBus 发布-订阅,松耦合,支持事件继承与多态分发 |
| 🤖 | 小车主平台 | 当前活跃系统聚焦 Ackermann 小车,测试平台用于本地联调 |
| 🧠 | 混合 AI | 三级语义:关键词 (零延迟) → Ollama 本地 LLM → 在线 LLM |
| 🗺️ | SLAM 建图 | 本地/远程/混合三模式,LiDAR → 后端建模 → 前端可视化 |
| 📊 | 实时监控 | MonitorAPI + 7 页 Web 控制面板,REST + WebSocket 双通道 |
| 🐳 | 一键部署 | docker compose up -d 启动后端 + MQTT + Nginx |
| ☁️ | COS 模型托管 | 腾讯云加速下载,--init 自动拉取,--upload 一键上传 |
更多特性
- 💬 智能对话 — 自然语言 → 意图解析 → 工作流编排 → 设备执行
- 🔐 JWT 认证 — 注册/登录/RBAC 角色权限 (admin / operator / viewer)
- 🏋️ 健身互动 — MoveNet 姿态检测 + 角度状态机,可扩展运动引擎
- 🛠️ CLI 工具链 —
--init初始化 /--test硬件测试,开箱即用 - 🎯 舵机校准 — 一键复位 + atexit 安全保护
| 层级 | 技术 |
|---|---|
| 机器人端 | Python 3.11 · asyncio · EventBus · 25 SubModules |
| 后端 | FastAPI · SQLAlchemy · JWT · Pydantic |
| 前端 | UniApp · Vue 3 · TMUI 3.2 · Pinia |
| 通信 | MQTT (paho) · WebSocket · msgpack · zlib |
| AI / ML | Whisper · YOLOv8 · MoveNet · Piper-TTS · NanoTrack |
| LLM | Ollama (本地) · OpenAI / Aliyun (在线) |
| 导航 | 2D SLAM · 定位质量门禁 · A* · DWA |
| 部署 | Docker Compose · Nginx · Mosquitto · uv |
git clone https://github.com/ZhuchenZhong/AC_FS32.git && cd AC_FS32
cp .env.example .env # 编辑填写配置
docker compose up -d # 后端 + MQTT + Nginx
# → http://localhost📋 .env 关键变量说明(点击展开)
| 变量 | 默认值 | 说明 |
|---|---|---|
AC_FS32_DEBUG |
false |
调试模式:自动启用 Monitor + MQTT 切换 localhost |
AC_FS32_PLATFORM |
car |
平台类型:test / car |
AC_FS32_MQTT_BROKER |
fs.k1d.tech |
MQTT broker 地址(DEBUG 时自动切换 localhost) |
AC_FS32_LLM_PROVIDER |
local |
LLM 提供商:local(Ollama) / cloud |
AC_FS32_ASR_PROVIDER |
whisper |
ASR 引擎:whisper(离线) / aliyun(在线) |
AC_FS32_TTS_ENGINE |
piper |
TTS 引擎:piper(离线) / aliyun(在线) |
AC_FS32_MONITOR_ENABLED |
false |
启用 Monitor 监控面板(端口 9090) |
AC_FS32_LOG_LEVEL |
DEBUG |
日志级别:DEBUG/INFO/WARNING/ERROR |
完整变量列表见 .env.example
uv sync
uv run python src/main.py --init # 首次: 检查依赖 + COS 下载模型
uv run python src/main.py # 启动系统
uv run python src/main.py --test # 集成测试(完整)
uv run python src/main.py --test quick # 集成测试(快速自检)
uv run python src/main.py --debug # 调试模式(自动启用 Monitor)cd backend && uv sync && uvicorn backend.main:app --host 0.0.0.0 --port 8000
cd frontend && npm install && npm run build📖 完整指南见 部署文档 · 平台切换:
config/system.json→platform.type(0=测试 / 1=小车)。历史小狗代码已迁入bak/puppy/ac_fs32/
25 个可插拔业务模块,按 config/submodules.json 配置启停:
| 领域 | 模块 |
|---|---|
| 语音 | 语音识别 (Whisper/Paraformer) · 唤醒词 (Snowboy/WonderEcho) · TTS (Piper/Sambert) · 交互编排 |
| 视觉 | YOLO 检测 · NanoTrack 追踪 · 颜色追踪 · 巡线 · 手势识别 · 人员跟随 · 跌倒检测 · QR 码 |
| 导航 | LiDAR 避障 · SLAM 建图 · A*/DWA 导航 · 感知融合 |
| 通信 | MQTT 客户端 · WebSocket 流 |
| LLM | 多 Provider 管理 · 混合语义 Agent |
| 控制 | Ackermann 底盘 · 校准 · 遥控 · 后端权威仿真接管 |
| 其他 | 日志系统 |
仿真模式现在由后端
simulation_runtime统一接管。进入仿真后,系统按选中的car/test作为 effective platform 运行,MonitorAPI 提供统一的仿真状态与场景接口,网页仿真页只负责输入、场景编辑和渲染。历史小狗与 PuppyFit 相关代码已迁入bak/puppy/ac_fs32/。
部分模块支持离线/在线双方案,通过 config 一键切换:
| 模块 | 离线 | 在线 |
|---|---|---|
| 语音识别 | Whisper | Aliyun Paraformer |
| 语音合成 | Piper | Aliyun Sambert |
| LLM | Ollama (0.5B~1.5B) | OpenAI / Aliyun |
| SLAM | 本地栅格 | 远程后端 |
AC_FS32/
├── src/ # 🤖 机器人端 (core/ + sub/ + model/ + web/)
├── backend/ # 🖥️ FastAPI 后端 (auth · devices · mapping · conversation)
├── frontend/ # 🌐 Vue 3 控制台 (Dashboard · Map · Chat · Settings)
├── config/ # ⚙️ JSON 配置 + 提示词 + 知识库
├── scripts/ # 🔧 部署脚本 + 模型工具 + COS 管理 + 演示物料生成
├── doc/ # 📖 文档 + 架构图 + 作品效果图
├── bak/ # 📦 历史归档(puppy/ac_fs32 历史代码与文档)
├── .plan/ # 🛠️ TaskFlow 任务计划(project_id=ac_fs32)
└── docker-compose.yml
| 文档 | 说明 | |
|---|---|---|
| 🏠 | 文档导航 | 按角色分类索引 (用户 / 开发者 / 架构师) |
| 🏗️ | 系统架构 | 核心组件、数据流、启动序列 |
| 🚀 | 部署指南 | Docker / 原生部署、故障排查 |
| ⚙️ | 配置参考 | 全部 config/*.json 字段说明 |
| 🧩 | 子模块开发 | 完整开发手册 |
| 🌐 | 后端 API | REST / WebSocket 端点文档 |
| 🛠️ | TaskFlow 流程 | TaskFlow MCP 任务编排(project_id=ac_fs32) |
| 🤝 | 贡献指南 | 开发环境、Git Flow、提交规范 |
| 📋 | 变更日志 | 版本历史 |
| 版本 | 里程碑 |
|---|---|
| v1.0 ✅ | 核心框架 — ROS2 → EventBus 迁移 |
| v1.1 ~ v1.3 ✅ | 通信层 + 前端控制台 + 安全加固 |
| v1.4 ~ v1.6 ✅ | 健身互动 + LLM 统一化 + CLI 工具链 |
| v1.7 ~ v1.10 ✅ | Monitor 系统 v5→v7 + WorkflowEngine |
| v1.11 ~ v1.14 ✅ | 文档补全 + 模型工具链 + COS 托管 |
| v1.15 ~ v1.17 ✅ | 模型容错 + 预制动作 + 子模块审计 + 架构图重绘 |
| v1.18 ~ v1.20 ✅ | UniApp + TMUI 跨平台迁移 + 注册/登录 + 桌面端适配 |
| v1.21 ~ v1.23 ✅ | 管理后台/教师端/成就系统 + 对话 DB 持久化 + 系统监控端点 |
| v1.24 ~ v1.25 ✅ | 全面安全审计 + 核心代码审计 (线程安全/资源泄漏) |
| v2.0 📋 | 小车能力深化 · 实时视频流 |