Skip to content

VM 多场景部署 · 多飞书机器人联调 ​

本页描述如何在 D2 云 VM 上启动多场景评委体系 — 每个 Scene 对应一个独立飞书机器人, 共用同一套 boss 判断引擎、wiki 知识库与锚点心智模型。

前置阅读: 多场景评委体系 · 部署指南


0. 架构总览 ​

飞书 (N 个机器人)
  │  机器人 A: review 场景        机器人 B: competition 场景
  │  收到文档                      收到方案
  ▼                                ▼
feishu_ws_client (单进程,N 条长连接,按 scene 路由)
  │
  ├─ scene A → job {scene_slug: "review-scene-a"}
  └─ scene B → job {scene_slug: "competition-scene-b"}
  ▼
review_worker (从 job.scene_slug 选对应 panel)
  │
  ├─ review-scene-a  → scenes/review-scene-a/panel.yaml  (100分, anchor judge)
  └─ competition-scene-b → scenes/competition-scene-b/panel.yaml (10分, 无 anchor)
  ▼
boss_server (HTTP API, port 8421)
  └─ GET /v1/scenes → 检查各场景 env 就绪状态

三个服务:

服务进程职责
boss-hermesuvicorn scripts.boss_server:appHTTP API + 健康检查 + /v1/scenes
boss-review-workerpython scripts/review_worker.py从 job 队列消费,调 LLM 跑评审流水线
boss-feishu-wspython scripts/feishu_ws_client.py飞书长连接,按 scene 路由事件

1. VM 准备 ​

1.1 推荐规格 ​

项推荐说明
CPU4C2C 可跑,但 worker 并发时慢
RAM8G4G 最低
OSUbuntu 22.04 LTS系统依赖最完整
公网 IP是飞书长连接是 outbound,无需开放入站

飞书长连接是 VM 主动连飞书,不需要 VM 开放任何入站端口给飞书。

1.2 安装依赖 ​

bash
sudo apt update && sudo apt install -y python3.11 python3.11-venv git curl

# 建专用用户
sudo useradd -r -m -d /home/boss -s /bin/bash boss
sudo -u boss bash

# clone vault
cd ~ && git clone https://github.com/zhanglunet/boss-vault.git
cd boss-vault

# 建 venv + 安装依赖
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install lark-oapi>=1.3.0   # 飞书长连接 SDK

# 验证
python3 -c "import fastapi, lark_oapi; print('deps OK')"

2. 配置 .env ​

2.1 复制模板 ​

bash
cp .env.example .env
chmod 600 .env

2.2 必填字段 ​

bash
# LLM (review worker 调用)
ANTHROPIC_API_KEY=<your-key>

# boss_server 认证 token (必须,无此字段 server 返回 503)
BOSS_API_TOKEN=$(openssl rand -hex 32)

# 飞书事件验证 token
FEISHU_VERIFICATION_TOKEN=<from-feishu-console>

# 每个 scene 各配一对 (从 scene.yaml feishu 块的 app_id_env / app_secret_env 取名)
LARK_APP_ID_<SCENE_A>=<app-id-from-feishu>
LARK_APP_SECRET_<SCENE_A>=<app-secret-from-feishu>

LARK_APP_ID_<SCENE_B>=<app-id-from-feishu>
LARK_APP_SECRET_<SCENE_B>=<app-secret-from-feishu>

# VM 只读标志 (避免 VM 写 _wiki/log.md 破坏 ff-only pull)
BOSS_VM_READER=1

查看每个 scene 需要哪些 env 变量名:

bash
python3 scripts/scene_loader.py list
# 输出示例:
# review-scene-a    type=review       bot_env=LARK_APP_ID_REVIEW_SCENE_A
# competition-scene-b  type=competition  bot_env=LARK_APP_ID_COMPETITION_SCENE_B

3. 飞书后台配置 ​

3.1 为每个 scene 创建独立飞书自建应用 ​

在 飞书开放平台 为每个 scene 各创建一个自建应用:

  1. 新建应用 → 自建应用 → 填写名称(建议与 scene 的 bot_name 一致)
  2. 权限管理 → 申请以下权限:
    im:message           # 接收消息
    im:message:send_as_bot  # 发送消息 (回推评审报告)
    im:resource          # 读取图片/文件
  3. 凭证与基础信息 → 复制 App ID / App Secret → 填入对应 env var

3.2 事件订阅 — 长连接模式(推荐) ​

飞书后台 → 事件订阅 → 选择「使用长连接接收事件」
添加事件: im.message.receive_v1

⚠️ 长连接与 webhook URL 二选一。用了长连接就不填 webhook URL,否则事件重复投递。

长连接优势: 无需公网入站端口、无需 HTTPS 证书、无需 URL 验证环节。


4. 部署 systemd 服务 ​

按顺序启动(boss-hermes 先起,review-worker 次之,feishu-ws 最后):

4.1 boss-hermes (HTTP API) ​

bash
VAULT_ROOT=/home/boss/boss-vault

sudo cp templates/boss-hermes.service.example /etc/systemd/system/boss-hermes.service
sudo sed -i "s|__VAULT_ROOT__|$VAULT_ROOT|g; s|__USER__|boss|g" \
    /etc/systemd/system/boss-hermes.service

sudo systemctl daemon-reload
sudo systemctl enable --now boss-hermes

# 验证
curl http://localhost:8421/v1/healthz
# → {"status": "ok", "timestamp": "..."}

4.2 boss-review-worker ​

bash
sudo cp templates/boss-review-worker.service.example /etc/systemd/system/boss-review-worker.service
sudo sed -i "s|__VAULT_ROOT__|$VAULT_ROOT|g; s|__USER__|boss|g" \
    /etc/systemd/system/boss-review-worker.service

sudo systemctl daemon-reload
sudo systemctl enable --now boss-review-worker

sudo systemctl status boss-review-worker

4.3 boss-feishu-ws (多 bot 长连接) ​

bash
sudo cp templates/boss-feishu-ws.service.example /etc/systemd/system/boss-feishu-ws.service
sudo sed -i "s|__VAULT_ROOT__|$VAULT_ROOT|g; s|__USER__|boss|g" \
    /etc/systemd/system/boss-feishu-ws.service

sudo systemctl daemon-reload
sudo systemctl enable --now boss-feishu-ws

# 验证多 bot 连接
sudo journalctl -u boss-feishu-ws -n 30 --no-pager
# 期望每个 env 已配置的 scene 各出现一行 "WS connected"

5. 验证检查清单 ​

5.1 静态链路校验(不调 LLM) ​

bash
cd ~/boss-vault && source .venv/bin/activate

# 各场景全链路静态检查
for scene in <scene-a-slug> <scene-b-slug>; do
  make smoke-scene SCENE=$scene && echo "✅ $scene"
done

# boss_server 场景状态(检查 env 是否就绪)
TOKEN=$(grep BOSS_API_TOKEN .env | cut -d= -f2)
curl -s -H "Authorization: Bearer $TOKEN" \
     http://localhost:8421/v1/scenes | python3 -m json.tool
# 期望: 每个 scene 的 feishu.env_ready = true

5.2 飞书端到端验证(需真实机器人) ​

不同场景按类型用不同评委编排(见 多场景评委体系 · 场景决定评委类型): review 场景用「锚点 + 多维度评委」,competition 场景用单一虚拟评价助手。

向 review 场景机器人 发送测试文档,验证:

  • [ ] 机器人回复评审报告
  • [ ] 报告含 6 段 (§1 总分 → §6 一页汇总表)
  • [ ] 总分制与 panel 的 total_max_score 一致 (通常 100)
  • [ ] 评委包含该 scene 配置的 anchor judge + 多个维度评委
  • [ ] 角色化维度评委的点评含标准免责声明(评委是判断框架,非真实人物本人)
  • [ ] 无其他 scene 的评委出现

向 competition 场景机器人 发送测试方案,验证:

  • [ ] 机器人回复评审报告
  • [ ] 总分为自定义分制 (如 10 分)
  • [ ] 用单一虚拟评价助手,无 anchor judge 信息
  • [ ] 评分维度与 panel scoring_lenses 一致

⚠️ 出站脱敏:评审报告含角色化评委的点评,群投递 / 外发前由 redact_review / 出站闸把关(评委 doctrine 源属内部资料,不随报告外泄)。

5.3 路由隔离验证 ​

bash
# 确认 feishu_ws 多 bot 路由日志
sudo journalctl -u boss-feishu-ws -f

# 发送文档到 scene A 机器人时,期望日志:
# [feishu_ws:scene-a] handled: {status: "queued", ...}
# 不应出现 [feishu_ws:scene-b] 的日志

# 确认 review_worker 使用了正确 panel
sudo journalctl -u boss-review-worker -f
# 期望: panel=scenes/<scene-a-slug>/panel.yaml

6. 常见问题 ​

长连接未建立 / scene 被跳过 ​

bash
sudo journalctl -u boss-feishu-ws -n 50
# 如果见到 "skip scene xxx: env LARK_APP_ID_xxx unset"
# → .env 里对应 env 变量未填

source .env && printenv | grep LARK_APP_ID

报告用了错误场景的评委 ​

bash
# 确认多 bot 路由是否生效
journalctl -u boss-feishu-ws | grep "starting scene bots"
# 期望: "[feishu_ws] starting scene bots: scene-a, scene-b, ..."

# 如果只见到单 bot 模式:
# "[feishu_ws] using fallback single-bot mode (LARK_APP_ID)"
# → 检查 scene.yaml 的 feishu 块是否配置,以及对应 env var 是否设置

boss_server 返回 503 ​

bash
# 原因: BOSS_API_TOKEN 未配置
grep BOSS_API_TOKEN .env

# healthz 永远 200,其余 endpoint 需要 token
curl http://localhost:8421/v1/healthz       # 200
curl http://localhost:8421/v1/scenes        # 401 (缺 token) 或 503 (未配置)

7. 服务日志位置汇总 ​

bash
# 三个服务的实时日志
sudo journalctl -u boss-hermes       -f   # HTTP API
sudo journalctl -u boss-review-worker -f  # LLM 评审 job
sudo journalctl -u boss-feishu-ws    -f   # 多 bot 长连接路由

# 查看所有三个服务的状态
sudo systemctl status boss-hermes boss-review-worker boss-feishu-ws

相关: 多场景评委体系 · 部署指南 · Hybrid 部署 · 故障排查 · ADR-012

判断力工程化 · Judgement, Engineered · 主站 · GitHub