DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

MoonightsZ /

MoonightsZ/dsh-qqbot-dispatch

Verified

本插件是 @tencent-connect/dsh-qqbot 的社区补充,可向 QQ 机器人建立的群聊或私聊会话下发任务,并在 DSH 侧栏查看会话、管理可自定义的功能模组。

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@921ecbd2

dsh-qqbot-dispatch

中文展示名称:QQ 机器人 · 通知助手。

本插件是 @tencent-connect/dsh-qqbot 的社区补充,可向 QQ 机器人建立的群聊或私聊会话下发任务,并在 DSH 侧栏查看会话、管理可自定义的功能模组。内置模组包括 CS2 赛事通知和偶尔闲聊,也可按需添加其他模组。

安装

先安装并配置 @tencent-connect/dsh-qqbot,再加入本插件:

dsh plugin --profile web add /abs/path/to/dsh-qqbot-dispatch

在 profile 的 cordis.patch.yml 为本插件指定与 qqbot 相同的 AppID:

- insert:
    - id: qqbot-dispatch
      name: 'dsh-qqbot-dispatch'
      config:
        appId: '<QQ Bot AppID>'

启用包含此补丁的 bundle,重启 Harness 后,侧栏会出现「QQ 机器人 · 通知助手」。如果已有旧配置,将 tool-qqbot-dispatch 行的 id 和包 name 一并更新;工具名称及 /qqbot-tool-dispatch/* 路径保持兼容。

使用说明

下发任务

插件提供两个工具:

工具 用途
qqbot_dispatch 向指定 QQ 群聊或私聊会话提交一项任务。接受后立即返回,不等待目标回合完成或把回复带回当前会话。
qqbot_sessions 列出 QQ Bot 已记录的会话映射;传入 scope 和 peerId 时解析单个目标。

qqbot_dispatch 的参数:

参数 说明
scope 必填。group 表示群聊,c2c 表示私聊。
peerId 必填。群聊填 group openid,私聊填用户 openid。
text 必填。提交给目标会话的任务内容。
mode 可选。queue 排队,steer 插入进行中的回合;默认 queue。

例如,向群聊下发任务:

{"scope":"group","peerId":"<group_openid>","text":"整理今天的讨论重点","mode":"queue"}

会话管理

侧栏「会话」页显示 QQ Bot 已映射会话的名称和活跃状态。群聊优先显示已同步的群名;私聊直接显示映射中的 user_openid,不将 DSH 会话标题当作 QQ 昵称。页面可见时每 20 秒重读列表;打开目标会话选择器或点击「刷新选项」也会更新候选会话,未保存的选择会保留。

操作 效果
刷新会话 只读取本地会话数据。
刷新群名 在对应群的会话行向 QQ 平台查询群信息并更新会话标题。
OpenID 复制该行的群或私聊用户 OpenID。

功能模组

「功能」页采用模组导航与配置区;配置区较窄时导航移到上方。切换模组不会清空尚未保存的表单。模组的「目标会话」留空时继承「配置」页的整组全局默认目标;也可为模组单独选择一组目标,整体覆盖全局设置。

模组 用途 详细说明
CS2 赛事通知 按队伍和等级筛选比赛,提供每日汇总、赛前提醒与赛果提醒。 查看模组说明
偶尔闲聊 按概率、小时冷却和安静时段,偶尔在指定会话发起聊天。 查看模组说明

全局默认目标会话

在「配置」页可同时选择群聊和私聊,每组最多 20 个目标。目标须先向 QQ Bot 发过消息,进入会话列表。选择器支持搜索、勾选、移除和刷新;已失效会话可移除,不能重新勾选。

未单独指定目标的模组会继承整组全局默认目标。页面会列出继承此设置的模组;修改默认目标会影响这些模组,已有独立目标保持不变。若已启用的模组仍在继承,须先为其指定独立目标或关闭模组,才能清空默认目标。运行时按目标顺序处理;一个目标失败不阻止其他目标,结果会显示部分成功与失败目标。

全局投递配置

「配置」页的开关作用于所有功能模组:

模式 CS2 赛事通知 偶尔闲聊
服务回合投递(默认) 固定赛事内容由 Agent 尽量原样输出;选择“AI 焦点分析”时,Agent 填充模板并生成分析。 Agent 结合会话上下文生成开场白。
直接发送 Markdown 调用上游 Bot 实例的 sendMarkdown 发送固定赛事正文;模板和焦点分析暂不生效。 将选中的话题作为开场白原文发送。

全局设置保存在 ~/.dsh-qqbot/dispatch-features.json 的 settings.defaultTargetSessionIds 和 settings.deliveryMethod 中;模组的独立目标保存在 target.sessionIds。旧单目标配置会自动迁移。各投递方式的限制见下方「资料与限制」。

常见问题

为什么直接发送提示“尚未取得 QQ Bot 实例”?

“直接发送 Markdown”需要先捕获 QQ Bot 的运行实例。启动或重启插件后,让机器人收到一条 QQ 消息即可;向目标群发送一条普通消息最方便,私聊会话则向机器人发送私聊消息。随后再尝试“立即发送”。每次进程重启后都需要重新收到一条消息。

使用服务回合投递也需要先发消息吗?

服务回合投递不依赖上述实例。若目标会话已由 QQ Bot 建立并记录,可直接选用;新群聊或私聊仍需先给机器人发消息,让目标会话出现在列表中。

资料与限制

数据存放

数据 位置或来源
功能状态、全局默认目标与投递设置 ~/.dsh-qqbot/dispatch-features.json
群名缓存、群可用状态 ~/.dsh-qqbot/group-names.json、~/.dsh-qqbot/group-health.json
数据源 API Key 宿主凭证服务;不写入功能状态文件。
QQ Bot 的 AppID/AppSecret profile 中的 im-qqbot 配置。

本插件的设计边界

事项 当前行为
会话目标 以 QQ Bot 的 model-prefs.json 当前 peer 映射为准;群名缓存只用于展示。不存在或已归档的会话不进入目标下拉框。服务回合和直接发送均拒绝未记录的映射,不把派生 session ID 当作已确认的 QQ 对象。
直接发送的 Bot 实例 通过运行时包装上游入站方法取得;启动后须先收到一条 QQ 消息。未取得实例时会报错,不会把赛事记为已通知。该模式依赖上游内部方法,版本变化时可能需要适配;qqbot_send_file 只用于附件,不发送聊天文字。
结果记录 服务回合显示「已提交」,直接发送显示「已调用上游发送」;这两种状态都不是 QQ 客户端的送达确认。
群不可用状态 群消息接口返回 HTTP 404 时,暂停该目标的赛事通知和闲聊,并从目标选项中排除;保留历史与配置。成功同步群名后恢复。查询失败、限流、超时或 HTTP 5xx 不会触发暂停。
扩展模组 启动时扫描 modules/*/module.json,新增模组默认关闭;关闭的扩展模组不能自动运行或手动试运行,也不会加载其 provider.js。启用后模组代码与 DSH 同进程运行,关闭开关不能卸载已加载的代码,须重启进程。此机制不提供进程隔离,只应启用已检查来源和代码的模组。

上游 DSH/QQ Bot 决定的行为

事项 影响
外部回合 qqbot_dispatch 提交外部回合;QQ 回复是否主动推送由上游 proactiveDelivery.externalTurns 控制。
服务回合 默认通知会恢复目标 Agent,提交来源为 plugin:dsh-qqbot-dispatch 的服务回合;这类回合不受 externalTurns 控制。提交和持久化成功只代表任务已受理,不代表 QQ 已送达。

QQ 平台决定的限制

事项 影响
主动消息权限与频率 服务回合推送和直接 sendMarkdown 都受 QQ 平台的权限、额度与频率限制;切换投递方式不能绕过。
群接口返回 404 仅凭 HTTP 404 无法区分群解散与机器人被移出,插件统一显示为「群不可用」。

开发说明

代码结构

.
├── index.js                     插件入口,组装服务、模组与路由
├── module-discovery.js          扫描模组清单,按需加载扩展代码
├── features.js                  全局配置、模组状态与排程
├── routes.js                    设置与会话接口
├── notification-dispatcher.js   全局通知投递策略
├── service-turn.js              服务回合投递
├── upstream-sender.js           调用上游 Bot 实例发送 Markdown
├── modules/
│   ├── cs2-matches/             CS2 赛事通知:定义、数据处理、模板与设置卡片
│   └── casual-chat/             偶尔闲聊:定义、触发逻辑与设置卡片
├── client/                      侧栏页面源码,含扩展模组通用配置卡片
├── client.js                    构建生成的前端文件
├── scripts/build.mjs            前端构建脚本
└── tests/                       模组、投递策略、路由与界面测试

扩展功能模组

插件启动时扫描 modules/ 的直属子目录。每个扩展模组遵循以下结构:

modules/<模组 ID>/
├── module.json     清单:id、名称、说明、配置字段和默认排程
├── provider.js     导出 createProvider(options),返回异步运行函数
└── README.md       可选的功能说明

module.json 只接受清单字段,扫描时不会执行模组代码。目录名须与清单 id 一致;新目录需要重启插件才能被发现。设置页使用通用配置卡片,不读取扩展模组的浏览器脚本。扩展模组不需要单独的 cordis.patch.yml:插件包根目录的补丁负责加载整个插件。

createProvider({ notificationDispatcher }) 返回的函数接收 { feature, settings, target, ctx, now, manual, forceResend },返回 { matched, sent, error?, channel? }。运行时按目标顺序调用 provider,每次 target.sessionId 仍是单个会话;结果通过 targetResults 汇总。内置模组的去重与冷却按会话隔离,扩展模组的自定义持久状态仍须自行按会话管理。新增模组默认关闭;只有用户手动启用后,调度或“立即运行”才会首次加载 provider.js。模组可通过 notificationDispatcher 遵循全局投递方式。内置的 CS2 与闲聊模组仍保留各自的专用设置卡片和 provider。

统一接口便于校验清单和控制启停,但不是安全沙箱。provider.js 是普通 Node.js 代码,一旦加载便拥有宿主进程的权限;只应安装并启用自己检查过来源和代码的模组。若要运行未经审核的第三方代码,需另行设计进程隔离与能力限制。

本地验证

npm install --legacy-peer-deps
npm test
npm run build

相关项目与设计参考

项目 借鉴点
dsh-context 使用 DSH 语义主题变量组织紧凑的信息卡与控件状态。
dsh-guizang-design 用清晰标题、细线和留白区分页面层级。
dsh-media-desk 响应式布局、统一的控件反馈与明暗主题适配。
dsh-qqbot-expands 运行时包装上游入站方法,取得 Bot 实例。

免责声明与许可

本项目是社区独立开发的非官方插件,与腾讯、DeepSeek 及 @tencent-connect/dsh-qqbot 的维护方无隶属关系,不代表其官方立场。

使用本插件即表示你已阅读并遵守 QQ 开放平台的相关规则。因违反平台规则而产生的后果,由使用者自行承担。

本项目采用 MIT 许可证 开源。软件按许可证“原样”提供,不附带任何明示或默示担保。

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout
—/ 5

No ratings yet

Verified DSH bundle

Commit 921ecbd23270

Community comments

No comments yet. Be the first to write one.