name: qiwei-webhook-relay

description: 企微消息运行时：个人版在客户主机主动轮询，企业版接入中央 Relay 统一回调。

Webhook 与 Relay

使用边界

先调用 qiwei_product_mode_status 判断产品模式。个人版由技能包内置 ESM Runtime 在客户主机主动轮询；企业版由同一 Runtime 进入中央 Relay 注册和服务端回调流程。

本 skill 负责：

查询 Relay 回调配置状态；
在中央 Relay 服务端注册租户、保存凭证；
通过 Fmode 服务端专用接口配置企微全局回调；
管理 Relay 配置。

标准产品流程只有 local_polling 和 server_relay 两种传输方式。旧的显式直连工具仅保留兼容，不作为个人版交付步骤。

模式说明

个人版本地轮询

运行 npm run runtime 后，ESM Runtime 复用现有 Agent Poller，通过 Fmode/Future Server 网关主动同步新消息，并将画像、待办、预警、草稿和会话数据保存在客户项目中。用户不需要配置公网地址。

企业版中央 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；
- 将当前设备注册到 Relay，用真实 guid 建立租户路由；
- 调用 Fmode 专用接口 POST /relay/connect；
- 由 Fmode 服务端使用服务端密钥，把 Token 级全局回调设为 {RELAY_BASE_URL}/api/webhook/ingest；
- 客户端不会接触或提交全局回调签名密钥；
- 返回配置结果，并由 MCP/Skill 自动确保 Relay 消费守护进程常驻。
企业版无需启动 Dashboard 或手工执行 npm run relay；守护进程使用 ESM Runtime，事件在服务端持久排队，本地处理成功后才 ACK。

手动注册 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 — 注册设备并通过 Fmode 专用接口接入中央 Relay
qiwei_relay_config — 读取 Relay 配置
qiwei_relay_save_config — 保存 Relay 公钥/租户配置
qiwei_relay_register — 注册 Relay 租户并保存凭证
qiwei_relay_connect — 配置 Relay 回调地址

本地模式工具仅供隔离部署使用；默认调用会被拒绝，防止共享 Token 的全局回调被个人电脑覆盖。

SKILL.md 3.8 KB Kalıcı Bağlantı Geçmiş Ham