前言¶
在 DSH（DeepSeek Harness / Cordis）里，Agent 通常只在用户发消息或工具被调用时才回应。若希望 Agent 在固定节奏或长时间未互动时「主动找用户聊」，需要定时唤醒、生成内容，并走 QQ 官方 Bot 的主动消息通道。dsh-suinian（碎念）就是面向这一需求的 Cordis 插件：随机心跳、空闲问候，以及会话内可调用的 qq_send 工具。它基于 QQ 开放平台 Bot API，不依赖 NapCat、SnowLuma 等第三方协议。
社区插件目录见 SkillHub 条目；源码与说明在 GitHub：meow09nine/dsh-suinian。维护者 GitHub 用户名为 meow09nine，package 作者署名为上若拾梦（Finnley_evokia）。当前 package 版本为 0.2.2，MIT License。另有一个同名 OpenClaw 包 suinian-heartbeat，宿主与配置均不通用，装错环境不会生效。
这是什么¶
dsh-suinian 是 DSH 0.2.x 下的联网类插件（社区分类：联网工具）。依赖：一个已在 QQ 开放平台注册的官方 Bot，以及已接入该 Bot 的 DSH profile（例如通过 @tencent-connect/dsh-qqbot）。必填配置为 Bot 的 appId、appSecret，以及接收主动消息用户的 c2c openId（用户先私聊 Bot 一条消息后，Bot 侧 author.id / 会话 targetId 即为此值）。
核心功能¶
以下能力均来自项目 README，已核实。
- 工具
qq_send(text)：Agent 在任意会话中可主动发一条 QQ 私聊消息。 - 随机心跳：在可配置日窗口（默认 8:00–24:00）内分窗口随机到点，唤醒 Agent 生成内容并发送。
- 事件触发：用户超过
idleHours（默认 3 小时）未说话时主动问候，带冷却与每日上限。 - 审计日志：默认写入插件目录
logs/suinian.log，记录 plan、唤醒、发送等；状态文件为suinian-state.json。
主动消息走官方接口 POST https://api.sgroup.qq.com/v2/users/{openId}/messages。额度为 1000 条/天/用户、20 条/分钟（README 说明）。群聊侧官方 Bot 通常只能 @ 触发，与本插件「主动私聊」场景不同。
安装与启用¶
README 未给出 dsh plugin add github:owner/repo 一类命令；安装按仓库说明顺序进行。
- 将发布包解压到任意目录。
- 填配置（二选一）：
- 交互式：node setup.mjs
- 手动：编辑目录内cordis.patch.yml，替换YOUR_APPID/YOUR_APPSECRET/YOUR_C2C_OPENID - 自检（建议先 dry-run，再真发一条）：
node selfcheck.mjs --dry-run # 只校验配置 + 拿 token，不发消息
node selfcheck.mjs # 真发一条测试消息
- 装入 DSH：
- 推荐：用 DSH 插件管理器对本目录执行install_bundle。
- 手动：目录放到目标 profile 的node_modules/dsh-suinian/，将 patch 中- insert:段合并进 profile 的cordis.patch.yml，重启 DSH。
合并 patch 时注意：新增行须用 - insert: 包裹；若写成 - id: 会尝试覆盖已有行，新行不存在时插件不会加载。
运行环境：Node.js >= 20（见 package.json engines）。
配置要点¶
cordis.patch.yml 的 config 中三项必填：appId、appSecret、openId。
常用可选项（默认值以 README 为准）包括：startHour / endHour（8 / 24）、windowMinutes（120）、每窗口次数 minPerWindow / maxPerWindow（3 / 4）、全局最小间隔 minGapMinutes（21）、每次唤醒连发条数 linesPerPoint（[2, 4]）、每日上限 maxPerDay（40）、空闲问候相关 idleHours、idleCooldownMs、maxIdlePerDay，以及 dryRun（true 时只记日志、不真发）。
建议启用顺序：先 dryRun: true 跑一两天看日志节奏，再关闭 dryRun；首日关注 plan / woke / sent / voided 等记录。
典型用法与工作方式¶
Agent 被定时器或空闲逻辑唤醒后，经 sessionController.prompt 生成内容，再调用 qq_send 完成发送。流程可概括为：
定时器到点 → 唤醒 agent 会话 → agent 生成内容 → qq_send
→ POST .../v2/users/{openId}/messages
自定义唤醒文案可使用 promptText / idlePromptText，支持 {lines} 占位（与 linesPerPoint 配合）。
适用场景与注意¶
适合：已在 DSH 中接入 QQ 官方 Bot、希望 Agent 私聊侧有「碎念式」主动触达（心跳 + 久未回复问候 + 随时工具发一条）的开发者。
注意：
- 插件以当前 DSH 进程权限运行；安装前请阅读源码与 MIT 许可证，自行评估凭证与 openId 存放方式。
- 过期时间窗不补发，避免重启后集中轰炸；有无人在线都有窗口次数与每日上限约束。
- 日志/状态默认在插件内
logs/，可用logFile/stateFile改路径。 - SkillHub 与 DeepSeek / 幻方无官方从属关系，目录为社区生态站点；DSH 本身遵循「一切皆插件」的扩展方式。
结尾¶
dsh-suinian 把「主动 QQ 私聊」拆成可配置的随机心跳、空闲问候和 qq_send 工具，并自带 setup、selfcheck 与 dry-run 路径，便于在真发前核对节奏与凭证。
- 目录页：https://www.skillhub.cn/plugins/meow09nine/dsh-suinian
- GitHub：https://github.com/meow09nine/dsh-suinian
