前言¶
在 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
