name: qiwei-webhook-relay

description: 企微 Webhook 与 Relay：仅支持中央 Relay 模式自动注册/配置、Relay 长轮询客户端。

Webhook 与 Relay

使用边界

本 skill 负责：

查询 Relay 回调配置状态；
在中央 Relay 服务端注册租户、保存凭证；
自动配置企微回调地址到 Relay；
管理 Relay 配置。

本地 webhook server 模式已禁用。 所有回调统一通过中央 Relay 接收。

模式说明

中央 Relay 模式（唯一可用）

企微平台把事件推送到 Fmode 中央 Relay 服务器（默认 http://8.138.37.248:4000），本地 Skill 通过长轮询主动取回属于自己的事件。适合 Skill 运行在本地电脑、内网或无固定公网 IP 的场景。

数据存储

Relay 配置：outputs/webhook/relay-config.json
回调事件：outputs/webhook/<date>/<time>-<source>/event-...json

标准流程

首次使用自动配置

确保 .env.local 已配置 QIWEI_AUTH_TOKEN。
调用 qiwei_login_start → 用户扫码登录。
登录成功后，调用 qiwei_webhook_auto_setup 或 qiwei_relay_connect：
- 提取并保存设备 guid；
- 在中央 Relay 注册租户（如未注册）；
- 保存租户凭证到 .env.local；
- 调用 /client/setCallback 把回调地址设为 {RELAY_BASE_URL}/api/webhook/ingest/{tenantId}/{guid}；
- 返回配置结果，并提示启动 Relay 轮询客户端。
在服务器上执行 npm run relay 启动长轮询（或使用 systemd/pm2 持久化运行）。

手动注册 Relay 租户

{
  "name": "qiwei_relay_register",
  "arguments": {
    "description": "本地 Skill",
    "force": false
  }
}

返回 tenantId、apiKey、apiSecret、privateKey，并自动保存到 .env.local。

手动配置 Relay 回调

{
  "name": "qiwei_relay_connect",
  "arguments": {
    "guid": "已登录设备 guid"
  }
}

Relay 客户端持久化运行

systemd

[Unit]
Description=Qiwei Relay Client
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/qiwei-assistant
EnvironmentFile=/opt/qiwei-assistant/.env.local
ExecStart=/usr/bin/node /opt/qiwei-assistant/scripts/start-relay-client.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启动：

sudo systemctl daemon-reload
sudo systemctl enable qiwei-relay
sudo systemctl start qiwei-relay

pm2

pm2 start scripts/start-relay-client.js --name qiwei-relay
pm2 save

MCP 工具

qiwei_webhook_status — 查询 Relay 回调配置状态
qiwei_webhook_auto_setup — 自动配置企微回调到 Relay（本地模式已禁用）
qiwei_relay_config — 读取 Relay 配置
qiwei_relay_save_config — 保存 Relay 公钥/租户配置
qiwei_relay_register — 注册 Relay 租户并保存凭证
qiwei_relay_connect — 配置 Relay 回调地址

已移除的本地模式工具：qiwei_webhook_discover、qiwei_webhook_server_start、qiwei_webhook_server_stop、qiwei_webhook_setup。

SKILL.md 3.0 KB История Исходник