碎念主动消息 meow09nine/dsh-suinian

dsh-suinian（碎念）

版本 v0.2.2 · MIT License · 作者：上若拾梦（Finnley_evokia）

让 DSH 智能体主动给用户发 QQ 消息：随机时间点心跳、长时间未互动问候、随时想发就发。

基于 QQ 官方 Bot 主动消息 API（私聊额度 1000 条/天/用户），不需要第三方协议（NapCat/SnowLuma）。

⚠ 两套宿主、两套实现，不通用：本包是 DSH（DeepSeek Harness / Cordis） 插件；另有一个同名的 OpenClaw 版 suinian-heartbeat，两者宿主不同、代码不同、配置不通用。装错宿主不会起作用。

依赖

- DSH 0.2.x（Cordis 插件宿主）
- 一个 QQ 官方 Bot（QQ 开放平台注册）
- 一个已接入该 bot 的 DSH 配置档（如通过 @tencent-connect/dsh-qqbot）

安装（按顺序）

1. 解压到任意目录。
2. 填配置（二选一）：
- 交互式向导：node setup.mjs（逐项问 AppID/AppSecret/openid 和发送节奏，自动生成配置）
- 手动：编辑本目录的 cordis.patch.yml，把 YOUR_APPID / YOUR_APPSECRET / YOUR_C2C_OPENID 换成你的值（见下面「配置」）
3. 自检（强烈建议，先确认能发再装）：

node selfcheck.mjs --dry-run # 只校验配置 + 拿 token，不发消息
node selfcheck.mjs # 真发一条测试消息，检查 QQ 是否收到

4. 装进 DSH：
- 方式一（推荐）：用 DSH 的插件管理器安装本目录（install_bundle）。
- 方式二（手动）：把本目录放到目标配置档的 node_modules/dsh-suinian/，再把 - insert: 那段并入配置档的 cordis.patch.yml，最后重启 DSH。

⚠ cordis.patch.yml 里的新行必须用 - insert: 包裹——写 - id: 是「覆盖已存在的行」，新行不存在会被跳过（插件不会加载）。

配置

必填三项（在 cordis.patch.yml 的 config 里）：

| 字段 | 含义 |
| appId | QQ 机器人 AppID |
| appSecret | QQ 机器人 AppSecret |
| openId | 接收主动消息的用户的 c2c openid |

怎么拿 openId：让用户先私聊 bot 一条消息，bot 收到的 author.id / 会话 targetId 就是它。

可选：

| 字段 | 默认 | 含义 |
| startHour / endHour | 8 / 24 | 随机时间窗口 |
| windowMinutes | 120 | 窗口长度（分钟） |
| minPerWindow / maxPerWindow | 3 / 4 | 每窗口随机次数 |
| minGapMinutes | 21 | 全局最小间隔（跨窗口也管，防连发） |
| linesPerPoint | [2, 4] | 每次唤醒连发几条（注入 prompt 的 {lines}） |
| catchupMinutes | 20 | 过期窗口：错过的点超过这个时长不补发 |
| maxPerDay | 40 | 每日上限 |
| idleHours | 3 | 用户多久不说话触发问候 |
| idleCooldownMs | 7200000 | 问候冷却 |
| maxIdlePerDay | 3 | 每日问候上限 |
| wakePreset | '' | 唤醒哪个预设会话，空 = 任意 |
| wakeTimeoutMs | 120000 | 单次唤醒超时（配合 in-flight 保护） |
| dryRun | false | 演练模式：只记日志、不真发（每天每条只记一次 dry-run） |
| logMaxBytes | 2097152 | 日志轮转阈值（超过后改名 .old） |
| checkMs | 60000 | 检查间隔（毫秒） |
| logFile / stateFile | 插件目录 logs/ | 日志/状态文件路径 |
| promptText / idlePromptText | 内置 | 自定义唤醒提示词（支持 {lines} 占位） |

日志和状态默认在插件目录的 logs/ 下（suinian.log / suinian-state.json），可用 logFile / stateFile 改到别处。

建议的启用顺序

1. dryRun: true 跑一两天 → 看日志里的 dry-run 节奏是否合适（每天每条只记一次）
2. 觉得可以了再关掉 dryRun 正式发
3. 首日观察 suinian.log 里的 plan / woke / sent / voided 记录

能力

- 工具 qq_send(text)：智能体在任何会话里都能主动发一条消息
- 随机心跳：每天 8:00–24:00 分窗口随机，到点唤醒智能体生成内容
- 事件触发：用户超过 idleHours 没说话 → 主动问候（带冷却与日上限）
- 审计日志：<插件目录>/logs/suinian.log，记录每次发送/唤醒/计划

工作方式

定时器到点 → 唤醒 agent 会话（sessionController.prompt） → agent 生成内容 → 调用 qq_send 工具 → POST https://api.sgroup.qq.com/v2/users/{openId}/messages

注意

- 主动消息额度：1000 条/天/用户、20 条/分钟
- 群聊：官方 bot 群聊只能 @ 触发（「接收所有消息」权限个人开发者通常没有）
- 过期时间点不补发（避免重启后轰炸）
- 无人值守时不会乱发：每窗口有次数上限、每日有上限
- 日志/状态文件默认放在插件内的 logs/ 目录，可以配置到别处