前言¶
在 DeepSeek Harness（DSH）里做自动化时，常见需求是「让智能体把结果推到 QQ」。只读聊天记录可以用 dsh-plugin-qqchat；一旦要在群里或私聊里主动发一条文本、表情、文件，就需要单独的「写」能力，并且默认不能误触真发。下面介绍社区插件 dsh-plugin-qqsend：经 OneBot/NapCat 发消息与文件，内置 dry-run 与多重安全闸门，与 qqchat 拆成两个 bundle，可分别启停。
这是什么¶
dsh-plugin-qqsend（当前仓库版本 v1.2.0）由维护者 jcy0chenyuan0 发布，分类为联网工具。简介：通过 OneBot/NapCat 发送 QQ 消息与文件，带 dry-run 与安全闸门。
与只读的 dsh-plugin-qqchat 完全独立。README 说明拆包原因：qqchat 的可信承诺是「绝对不发消息」；读写若在同一插件里，该承诺无法成立。
代码里写死的红线包括：一次调用只发一条、不批量群发；不自动回复、不订阅消息；不做频率规避；不注入 QQ 进程、不改安装包、不重实现 QQ 协议。
核心功能¶
发送与附件¶
| 工具 | 作用 |
|---|---|
qq_send |
向指定群或好友发一条消息；支持系统表情、贴图、连发、引用 |
qq_send_file |
上传一个本地文件或 URL 到群/好友 |
qq_schedule |
定时任务：add / list / remove / run（到点发送需外部调度调用 run） |
qq_stickers |
查询可用表情包（会话最近或收藏） |
qq_send 常用参数：faces（小黄脸编号或名字）、stickers（贴图 URL 或 "latest"）、messages（连发数组，默认间隔 900ms）、quote（引用 message_id）。
文件上传边界：单次只传一个文件；上传前校验存在且为普通文件；超过 100MB 会提醒但不阻止；审计只记文件名与大小，不记本机完整路径。
诊断、目标与登录¶
| 工具 | 作用 |
|---|---|
qq_send_doctor |
通道是否可用、当前登录 QQ 号、总开关/白名单/限速/审计、目标索引 |
qq_send_targets |
按群号/群名/好友号/好友名搜索目标 |
qq_login_qrcode |
在 GUI 返回登录二维码（Markdown 图片） |
qq_send_history |
查看发送审计记录 |
媒体下载¶
qq_download_media 将收到的图片/文件/视频/语音增量下载到系统「下载」目录（可 dry_run、轮询、指定类型与目录）。游标在 ~/.qqsend/media-cursor.json。
三道锁：何时才会真发¶
真实发送需同时满足：
config.json中safety.allowSend = true（默认false）；- 调用参数
confirm = true（缺省为 dry-run，不发 HTTP）； - 目标在
safety.allowlist内（若配置了白名单）。
另有 maxPerMinute、maxPerTargetPerHour 限速，以及审计日志 ~/.qqsend/sent.log（不存完整正文）。
OneBot 通道仅接受 127.0.0.1 / localhost；配置 token 时请求带 Authorization: Bearer。README 明确提示：机器人框架登录 QQ 与腾讯用户协议存在冲突，存在封号风险，建议用小号作发送端。
安装与启用¶
首次安装需在本插件目录执行安装脚本，再在 DSH 里以本地路径安装 bundle。
Windows：
powershell -ExecutionPolicy Bypass -File .\install.ps1
macOS / Linux：
node install.mjs
脚本会按当前目录生成 cordis.patch.yml（已 .gitignore）。随后在 DSH：设置 → 插件 → 安装 → 本地路径，填写本目录绝对路径；或按 README 使用 plugin_manager install_bundle file:<本目录的绝对路径>。
配置步骤：
- 复制
config.example.json为config.json并按需修改； - 重启 DSH（改代码不热生效）。
关键配置示例：
{
"transport": "onebot",
"safety": { "allowSend": false, "maxPerMinute": 5, "maxPerTargetPerHour": 20, "allowlist": [] },
"onebot": { "baseUrl": "http://127.0.0.1:3000", "token": "" },
"qqchat": { "decryptedDir": null }
}
真实发送需要本机 NapCat（或 LLOneBot）提供 OneBot 11 HTTP；NapCat 不从 winget 自动装，需在 config.json 的 napcat.dir 或环境变量 NAPCAT_HOME 指向安装目录。安装脚本可默认静默补 Python、QQ NT 等；仅检查时 Windows 可加 -CheckOnly。关闭自动安装可在 patch 的 config 设 autoInstall: false，或 DSH_BOOTSTRAP=0。
运行环境说明：Windows 10/11（x64）为当前主要适配；Python 3.11+（优先 DSH 自带运行时）；macOS / Linux 的 OneBot HTTP 理论可用，本地路径与下载目录逻辑尚未完整移植。
典型用法¶
默认调用只做 dry-run，回显意图而不发请求：
qq_send(to="<群名或群号>", text="hello，你好世界")
真发需 confirm=true 且 allowSend=true：
qq_send(to="<群号或好友号>", text="hello，你好世界", confirm=true)
qq_send(to="<群号或好友号>", text="看这个", faces=["13"])
qq_send(to="<群号或好友号>", stickers=["https://.../a.gif"], confirm=true)
qq_send(to="<群号或好友号>", messages=["在吗","问你个事","那个文件还在不"])
qq_send(to="<群号或好友号>", text="收到", quote="123456789")
文件与定时：
qq_send_file(to="<群号或好友号>", file=r"<文件绝对路径>")
qq_send_file(to="<群号或好友号>", file=r"<文件绝对路径>", name="实验报告.pdf", confirm=true)
qq_schedule(action="add", to="<群号或好友号>", text="记得喝水", every=60)
qq_schedule(action="run", confirm=true)
插件自身不带常驻进程；无人值守定时发送需在外部计划任务中定期执行：
python -m qqsend schedule run --confirm
体检与媒体：
qq_send_doctor()
qq_download_media()
qq_download_media(dry_run=true)
适用场景与注意¶
适合：已在 DSH 里编排任务，需要可控、单次、可审计地向一个 QQ 群或好友推送文本、表情、单个文件，且愿意自备 NapCat/OneBot 并承担协议与账号风险。
不适合：群发、自动回复机器人、绕过限速或风控——这些在设计上被排除。
插件以当前 DSH 进程权限运行；安装前应阅读仓库源码与 MIT 许可证，核对 safety 默认值与白名单。仓库 README 记录本地假 OneBot 下 9/9 端到端测试通过；真实 NapCat 发送验收仍标记为待完成项。
DSH 社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；星标与分类信息以目录页为准。
链接¶
- 目录页：https://www.skillhub.cn/plugins/jcy0chenyuan0/dsh-plugin-qqsend
- 仓库：https://github.com/jcy0chenyuan0/dsh-plugin-qqsend
