03 · 快速开始

目标：30 分钟内，让一台平板（或手机）上的企业微信自动回第一条消息。

0. 你要准备

1. 起服务端

1.A 方式一：源码 + venv（推荐，与作者的生产环境一致）

git clone https://github.com/sevfish-ai/sevfish-comvbot-server.git sevfish-comvbot-server
cd sevfish-comvbot-server

python3 -m venv ../venv                      # 3.14，虚拟环境放仓外
../venv/bin/pip install -r fastapi/requirements.txt

cp .env.example .env
chmod 600 .env

先准备数据库（本机 MySQL 8）：

CREATE DATABASE aivbot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'aivbot'@'localhost' IDENTIFIED BY '换一个强口令';
GRANT ALL PRIVILEGES ON aivbot.* TO 'aivbot'@'localhost';
FLUSH PRIVILEGES;

编辑 .env，至少改这三处：

MYSQL_USER=aivbot
MYSQL_PASSWORD=换一个强口令          # 与上面 CREATE USER 一致
SITE_URL=http://192.168.1.10:8765    # 对外地址，客户控制台链接会用到

前台起一次，确认能连上库：

cd fastapi && ../venv/bin/python run.py

看到这两行即成功：

Uvicorn running on http://0.0.0.0:8765
📍 MySQL: aivbot@127.0.0.1:3306/aivbot

Ctrl-C 退出。长期运行交给 systemd（unit 文件、开机自启、日志查看见 06-自建部署 §2），不要用 nohup 或 &。

打开 http://<服务器IP>:8765/admin/orgs —— 这是管理后台的第一层：组织选择页。

数据库表会在首次启动时自动创建，不需要跑 SQL。 服务端开 reload=True 会清空内存中的 WebSocket 注册表，导致设备"假掉线"，所以默认关闭，别改。

1.B 方式二：Docker（可选，仅本机试玩）

仓库带了 Dockerfile + docker-compose.yml（MySQL 也在里面）。这条路径没有经过生产验证，只适合在自己机器上快速看界面：

cp .env.example .env       # 填 MYSQL_ROOT_PASSWORD 与 MYSQL_PASSWORD
docker compose up -d
docker compose logs -f server

（可选）一键开通一套演示数据

fastapi/provision_launch.py 会把组织、智能体、知识库、表格、工作流、任务、设备、记忆集一次建好：

# 方式一（venv）
cd fastapi && ../venv/bin/python provision_launch.py --check        # 只自检
cd fastapi && ../venv/bin/python provision_launch.py --api-key sk-xxx

# 方式二（docker）
docker compose exec server python provision_launch.py --check

知识库正文来自 fastapi/samples/knowledge/*.md（示例两份，替换成你自己的产品资料即可）；目录为空时只是把知识库建成空的，不会中断开通，之后可在「知识库」页上传。

2. 建组织与智能体

1. /admin/orgs → 新建组织（例：demo）
2. 进组织 → 侧边栏 智能体 → 新建：填服务商、模型、base_url、API Key、system prompt
3. 同一页勾选它被允许用的工具：联网 (enable_http)、建表、建任务、设备指令（至少勾 203 发送消息）
4. 设备页 → 新增设备：随便给个设备号（如 demo0001），绑定刚才的智能体

3. 装客户端

cd sevfish-comvbot-app
./gradlew assembleDebug          # 需要 JDK 8/11 + Android SDK，详见 09
adb install -r app/build/outputs/apk/debug/app-debug.apk

执行端（平板 / 手机）上：

1. 打开 APP → 设置 → 填服务器地址 192.168.1.10:8765（可带 ws:// 前缀）
2. 按引导开启 无障碍服务（系统设置 → 无障碍 → SevFishComVBot）
3. 允许"后台运行 / 电池不优化"，否则息屏后循环会被杀
4. 回到 APP，设备号与后台 demo0001 一致 → 后台设备页状态变为在线

客户端只做执行，不联网也能启动，但没有任何功能。

4. 配一条自动回复

1. 后台 → 组织 → 侧边栏 回复策略 → 选设备
2. 外部私聊：mode = reply；外部群：mode = reply_all（先都设成"回"，跑通再精细）
3. 合并窗口 建议先设 4~5 秒（生产再调大），否则一条消息一条回复会很吵
4. 保存

5. 验收

用另一个企业微信小号给这台设备发一句"在吗"：

• 后台 → 顶栏 功能测试 页：能看到 101 事件、能看到 203 下发与设备回执
• 平板 / 手机：企业微信自动进入该会话并回复
• 后台 → 设备 → 该设备 企微名 可点「获取名字」刷新（群聊 @ 判定需要它，见 04）

回执里看到 success_list 有目标房间、fail_list 为空即为成功。失败按功能测试页的 设备错误日志（type=302）排查。

6. 下一步