DooTask「我的机器人」应用使用指南:自建消息机器人的创建、配置与 Webhook 接入

原创2026-10-14 20:29:522,294 阅读
文章标签:后端前端桌面应用协同办公

DooTask「我的机器人」应用使用指南:自建消息机器人的创建、配置与 Webhook 接入

「我的机器人」是 DooTask 应用中心内置的 mybot 系统应用,面向所有登录用户提供消息机器人的全生命周期管理:查看、新建、修改、删除自建机器人,并可配置头像、名称、消息保留天数、Webhook URL 与 Webhook 事件订阅。本文将结合前端入口、后端 API 与消息处理任务的源码实现,讲解如何通过「我的机器人」把外部系统接入 DooTask 消息体系,并说明系统机器人与自建机器人之间的权限差异和各类限制。读完本文,你将掌握机器人的创建流程、字段含义、Webhook 事件订阅机制、回调请求体结构,以及通过斜杠指令管理机器人的完整实战方案。

是什么:mybot 系统应用

在 DooTask 应用中心的 11 个固定系统应用中,mybot(我的机器人)卡片对应着自建消息机器人管理入口。系统应用是主程序在应用中心「常用」区硬编码的内置入口,所有登录用户可见(见 resources/ai-kb/zh/concept/apps/system-apps/list.md)。

从后端实现看,「我的机器人」的核心数据由 user_bots 表承载,对应模型 app/Models/UserBot.php。每个自建机器人本质上是一个特殊用户账号(users.bot = 1),它与创建者的归属关系、消息清理天数、Webhook 配置都记录在 user_bots 表中:

字段 类型 说明
userid int 所属人(创建者)ID
bot_id int 机器人用户 ID(关联 users.userid)
clear_day int 消息自动清理天数
clear_at datetime 下一次清理时间
webhook_url string 消息 Webhook 回调地址
webhook_num int Webhook 请求累计次数
webhook_events array Webhook 事件订阅配置(JSON 存储)

机器人账号本身拥有独立的 userid、token、头像和昵称,可以像普通用户一样被加入会话、收发消息、被 @ 触发,但不能登录 UI。它通常用于自动通知、外部系统接入和 AI 对话(见 resources/ai-kb/zh/concept/bot/overview.md)。

入口位置

「我的机器人」在不同终端的入口如下:

  • 桌面端:左侧导航「应用」→「我的机器人」卡片
  • 移动端:底部 Tabbar「应用」→「我的机器人」
  • 进入后,抽屉右上角的「添加机器人」按钮可新建机器人

前端入口实现在 resources/assets/js/pages/manage/application.vue 的应用中心页面中,机器人列表与编辑交互则对应后端 api/users/bot/* 系列接口。

操作步骤

  1. 打开应用中心,点击「我的机器人」卡片。
  2. 抽屉内显示当前用户创建的机器人列表;若尚未创建任何机器人,会提示「您没有创建机器人」。
  3. 对列表中的每条机器人可执行三种操作:
    • 开始聊天:打开与该机器人的私聊会话;
    • 修改:编辑机器人基本信息和 Webhook 配置;
    • 删除:需输入备注原因;系统内置机器人不可删除。

删除动作对应的后端接口是 api/users/bot/delete(bot__delete)。源码位于 app/Http/Controllers/Api/UsersController.php,其校验逻辑依次为:

  • remark(删除备注)必填,且长度 ≤ 255 字符,否则分别报「请输入删除备注」「删除备注长度限制255个字」;
  • 目标必须是 users.bot = 1 的机器人,否则报「机器人不存在」;
  • 非本人拥有的机器人,若属于系统机器人(邮箱以 @bot.system 结尾)则报「系统机器人不能删除」,否则报「不是你的机器人」;
  • 校验通过后调用 $botUser->deleteUser($remark) 完成删除。

字段说明

「我的机器人」编辑面板中的字段与后端字段一一对应:

字段 说明 后端校验 / 边界
名称 机器人昵称 2–20 字符,过短或过长都会被拒(报「机器人名称由2-20个字符组成。」,见 UserBot::newBot)
消息保留 单位天,默认 90 天 取值范围 1–999,超出会被 min(max(intval(...), 1), 999) 钳制(见 bot__edit)
Webhook URL 收到机器人对话消息时回调的地址 最长 255 字符,必须 http:// 或 https:// 开头,否则不发送
Webhook 事件 勾选要订阅的事件类型 仅限内置 4 类事件,不可自定义事件名

其中 clear_day(消息保留天数)在源码中体现为 user_bots.clear_day,配合 clear_at 决定定时清理任务何时删除机器人会话中的过期消息。Webhook 事件的合法取值由 UserBot::webhookEventOptions() 返回,其余字符串会被 normalizeWebhookEvents 过滤掉,无法自定义事件名。

名称与会话开关

创建机器人时(对应 api/users/bot/edit 接口且 id 为空),后端调用 UserBot::newBot($userid, $name, $session)。其中:

  • session 参数(0/1)决定是否开启「新会话 / 历史会话」菜单,仅新建时生效,创建后不能更改,需要重建机器人;
  • 开启 session 后,机器人对话窗口会出现新会话、历史会话菜单,且 Webhook 回调消息中会多出 session_id 字段;
  • 机器人类型标识为 user-session-*(开启会话)或 user-normal-*(普通),与系统机器人的 @bot.system 邮箱后缀区分。

底层实现:机器人的创建与校验

UserBot::newBot 的实现(app/Models/UserBot.php)揭示了三个关键约束:

  1. 数量上限:通过 users 表关联 user_bots 表统计该用户拥有的机器人数量,达到 50 个时报「超过最大创建数量」;
  2. 名称校验:名称长度必须在 2–20 字符之间;
  3. 会话创建:创建成功后自动通过 WebSocketDialog::checkUserDialog 建立机器人私聊会话,并发送一条 /hello 模板消息提示「创建成功」。

编辑操作对应 app/Http/Controllers/Api/UsersController.php 的 bot__edit 方法:管理员可以借此接口修改系统机器人(仅限有限字段),普通用户只能编辑属于自己的机器人,否则返回「不是你的机器人」或「权限不足」。头像字段的更新会经过 Base::unFillUrl 处理并跳过 avatar/ 内置路径,确保头像引用合法。

Webhook 事件订阅与回调机制

Webhook 是把「机器人收到的事件」通过 HTTP POST 推送到外部服务的机制。后端在 UserBot 中定义了 4 个事件常量(app/Models/UserBot.php):

事件 key 触发时机
message 机器人收到消息(单聊任意消息;群聊需 @ 机器人)
dialog_open 用户首次打开与机器人的会话
member_join 群聊里机器人或他人加入
member_leave 群聊里成员离开

相关规则:

  • 不勾选任何事件时,normalizeWebhookEvents 默认按 [message] 处理;
  • shouldDispatchWebhook 会先校验 webhook_url 非空且以 http:// 或 https:// 开头,再判断事件是否在订阅列表内;
  • dispatchWebhook 使用 Ihttp::ihttp_post 发起 POST 请求,超时 30 秒,超时不重试;请求成功后累加 webhook_num 计数。失败仅在 info 日志中记录 webhook_url、data 与 error,没有死信队列或重试机制。

消息事件的完整调用链

当机器人收到一条消息时,系统会投递 BotReceiveMsgTask 任务(app/Tasks/BotReceiveMsgTask.php)异步处理,关键流程如下:

  1. 有效性校验:确认发送者是机器人(users.bot = 1)、消息存在;若消息本身就是机器人发的则直接忽略——这是为了避免机器人之间互相触发形成死循环;
  2. 指令提取:通过 extractMessageContent() 提取文本(含被引用回复的 reply_text);
  3. Webhook 推送:调用 handleWebhookRequest 处理事件分发;
  4. 会话回复:若为私聊(dialog->type === 'user'),继续处理签到机器人、匿名机器人等系统逻辑。

对于用户自建机器人,handleWebhookRequest 中有两条重要规则:

  • 斜杠指令被忽略:用户自建机器人收到以 / 开头(如 /help)的消息直接返回,不会触发 Webhook——斜杠指令仅对系统机器人(如 bot-manager@bot.system)有效;
  • 订阅过滤:只有 shouldDispatchWebhook(message) 通过(已订阅 message 事件且 URL 合法)才会推送。

Webhook 回调请求体字段

event = message 时的主要字段如下(见 resources/ai-kb/zh/concept/bot/webhook.md):

字段 说明
event 固定为 message
text 用户的纯文本指令
reply_text 若是引用回复,被引用消息的文本
token 机器人当次有效的 API token,可调用 DooTask API 代发消息
dialog_id / dialog_type / session_id 会话标识;开启 session 的机器人才有 session_id
msg_id / msg_uid / mention 消息 ID、发送者用户 ID、是否被 @
bot_uid 机器人 userid
msg_user 发送方信息(userid / email / nickname / 临时 token 等)
extras JSON 字符串,含 timestamp 等扩展信息
version 当前 DooTask 版本

这些字段在 BotReceiveMsgTask::handleWebhookRequest 中统一组装(app/Tasks/BotReceiveMsgTask.php),其中 token 由 User::generateToken 生成,msg_user.token 是有效期 1 小时的临时 token,外部服务可以凭此调用 API 代机器人回复。

回调响应与自动回复

外部服务收到 POST 后,若返回 JSON {"code":200,"message":"..."},DooTask 会把 message 内容作为机器人的文本回复发回原会话(app/Tasks/BotReceiveMsgTask.php)。这是「外部系统 → 机器人 → 会话」闭环回复的最简实现路径。

需要注意:

  • 不支持鉴权签名(如 HMAC),建议使用 HTTPS 并在服务端校验 token 字段;
  • 回调失败不重试、无死信队列,排查问题需查看后端 info 日志。

用斜杠指令管理机器人

除了「我的机器人」面板,还可以在 bot-manager@bot.system(机器人管理)的私聊中通过斜杠指令管理自建机器人(指令处理见 app/Tasks/BotReceiveMsgTask.php):

指令 作用
/list 列出「我的机器人」(最多 50 条,无则提示「您没有创建机器人。」)
/newbot 名称 创建机器人(名称 2–20 字符)
/setname <bot_id> <名称> 修改机器人名称(由机器人管理执行)
/deletebot <bot_id> 删除机器人
/token <bot_id> 获取机器人 token
/revoke <bot_id> 重置机器人 token(更换 encrypt 与 password)
/clearday <bot_id> <天数> 设置保留消息天数(默认取 30,上限 999)
/webhook <bot_id> <url> 设置 Webhook 地址(≤ 255 字符,清空则传空字符串)
/dialog <bot_id> <关键词> 搜索机器人的会话列表
/api 输出 API 接口文档入口与版本号

在机器人自己的单聊里,也可以直接对「自己的机器人」使用这些指令(/list、/newbot 除外,这两项仅限机器人管理)。获取 token 后,外部代码即可凭 token 调用 DooTask API 代机器人发消息。

系统机器人与自建机器人的差异

「我的机器人」列表中可能会出现系统机器人条目,两者权限差异明显:

  • 系统机器人:邮箱以 @bot.system 结尾,名单写死在 UserBot::systemBotName(app/Models/UserBot.php),如「系统消息」「任务提醒」「签到打卡」「会议通知」「审批」以及各 AI 对话机器人。普通用户不能删除(删除会报「系统机器人不能删除」),编辑时会显示「正在修改系统机器人」红色提示,只能修改有限字段,且仅管理员有权限;
  • 自建机器人:归属创建者本人,可自由修改名称、头像、clear_day、Webhook 配置,删除需填写备注;创建后不能跨账号转让,也不能把已有普通用户改成机器人。

一个机器人只能绑定一个 Webhook URL;Webhook 事件订阅仅限主程序内置的 message / dialog_open / member_join / member_leave 四类,不可自定义事件名。

限制与边界汇总

综合「我的机器人」面板、创建接口与消息处理任务,自建机器人存在以下边界(可作为开发与排障参考):

  • 单个用户最多创建 50 个自建机器人,超出报「超过最大创建数量」;
  • 机器人名称 2–20 字符;
  • clear_day 范围 1–999 天,默认 90 天;
  • Webhook URL 最长 255 字符,必须 http(s):// 开头;
  • Webhook 调用超时 30 秒,失败不重试、无死信队列;
  • 用户自建机器人不识别斜杠指令(/... 直接忽略,不触发 Webhook);
  • 机器人之间不会互相触发(避免死循环);
  • 群聊中必须 @ 机器人(或 AI 机器人被 @)才会触发回复;单聊中任意消息都会触发;
  • 机器人加入全员群、部门群、项目讨论组通常不被允许(这些群成员由系统自动维护),详见 resources/ai-kb/zh/howto/bot/invite.md。

小结

「我的机器人」(mybot 系统应用)是 DooTask 消息机器人的统一管理入口:创建与编辑走 api/users/bot/edit,删除走 api/users/bot/delete,消息接收与 Webhook 分发由 BotReceiveMsgTask 异步完成,数据层由 app/Models/UserBot.php 承载。理解 user_bots 表的字段含义、4 类 Webhook 事件的触发条件、回调请求体结构与「code:200 + message」响应约定,就能把任意外部系统(监控告警、工单流转、AI 服务等)以最低成本接入 DooTask 的即时消息链路。

登录后查看全文
dootask