dsh-qqbot-plus 0.0.0-stage → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (301) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/CHANGELOG_EN.md +188 -0
  3. package/LICENSE +21 -0
  4. package/README.md +281 -2
  5. package/README_EN.md +248 -0
  6. package/cordis.patch.yml +163 -0
  7. package/cordis.yml +112 -0
  8. package/install.sh +108 -0
  9. package/lib/alarms.js +371 -0
  10. package/lib/client.js +2411 -0
  11. package/lib/commands/auth.d.ts +18 -0
  12. package/lib/commands/auth.d.ts.map +1 -0
  13. package/lib/commands/auth.js +15 -0
  14. package/lib/commands/auth.js.map +1 -0
  15. package/lib/commands/help.d.ts +10 -0
  16. package/lib/commands/help.d.ts.map +1 -0
  17. package/lib/commands/help.js +39 -0
  18. package/lib/commands/help.js.map +1 -0
  19. package/lib/commands/index.d.ts +15 -0
  20. package/lib/commands/index.d.ts.map +1 -0
  21. package/lib/commands/index.js +30 -0
  22. package/lib/commands/index.js.map +1 -0
  23. package/lib/commands/misc.d.ts +21 -0
  24. package/lib/commands/misc.d.ts.map +1 -0
  25. package/lib/commands/misc.js +93 -0
  26. package/lib/commands/misc.js.map +1 -0
  27. package/lib/commands/model.d.ts +6 -0
  28. package/lib/commands/model.d.ts.map +1 -0
  29. package/lib/commands/model.js +63 -0
  30. package/lib/commands/model.js.map +1 -0
  31. package/lib/commands/new.js +17 -0
  32. package/lib/commands/preset.d.ts +8 -0
  33. package/lib/commands/preset.d.ts.map +1 -0
  34. package/lib/commands/preset.js +56 -0
  35. package/lib/commands/preset.js.map +1 -0
  36. package/lib/commands/session.d.ts +14 -0
  37. package/lib/commands/session.d.ts.map +1 -0
  38. package/lib/commands/session.js +34 -0
  39. package/lib/commands/session.js.map +1 -0
  40. package/lib/commands/status.d.ts +7 -0
  41. package/lib/commands/status.d.ts.map +1 -0
  42. package/lib/commands/status.js +26 -0
  43. package/lib/commands/status.js.map +1 -0
  44. package/lib/commands/types.d.ts +21 -0
  45. package/lib/commands/types.d.ts.map +1 -0
  46. package/lib/commands/types.js +2 -0
  47. package/lib/commands/types.js.map +1 -0
  48. package/lib/config.d.ts +95 -0
  49. package/lib/config.js +88 -0
  50. package/lib/features/answer-parser.d.ts +9 -0
  51. package/lib/features/answer-parser.d.ts.map +1 -0
  52. package/lib/features/answer-parser.js +23 -0
  53. package/lib/features/answer-parser.js.map +1 -0
  54. package/lib/features/approval-channel.d.ts +94 -0
  55. package/lib/features/approval-channel.d.ts.map +1 -0
  56. package/lib/features/approval-channel.js +158 -0
  57. package/lib/features/approval-channel.js.map +1 -0
  58. package/lib/features/approval-renderer.d.ts +18 -0
  59. package/lib/features/approval-renderer.d.ts.map +1 -0
  60. package/lib/features/approval-renderer.js +52 -0
  61. package/lib/features/approval-renderer.js.map +1 -0
  62. package/lib/features/button-utils.d.ts +34 -0
  63. package/lib/features/button-utils.d.ts.map +1 -0
  64. package/lib/features/button-utils.js +27 -0
  65. package/lib/features/button-utils.js.map +1 -0
  66. package/lib/features/history-store.d.ts +8 -0
  67. package/lib/features/history-store.d.ts.map +1 -0
  68. package/lib/features/history-store.js +23 -0
  69. package/lib/features/history-store.js.map +1 -0
  70. package/lib/features/question-channel.d.ts +96 -0
  71. package/lib/features/question-channel.d.ts.map +1 -0
  72. package/lib/features/question-channel.js +234 -0
  73. package/lib/features/question-channel.js.map +1 -0
  74. package/lib/features/question-renderer.d.ts +20 -0
  75. package/lib/features/question-renderer.d.ts.map +1 -0
  76. package/lib/features/question-renderer.js +70 -0
  77. package/lib/features/question-renderer.js.map +1 -0
  78. package/lib/fishcheck/measure.js +230 -0
  79. package/lib/fishcheck/rules.js +99 -0
  80. package/lib/fishmeme/plugin.js +605 -0
  81. package/lib/fishmeme/routes.js +141 -0
  82. package/lib/fishmemory/plugin.js +1052 -0
  83. package/lib/gateway/bootstrap.d.ts +12 -0
  84. package/lib/gateway/bootstrap.d.ts.map +1 -0
  85. package/lib/gateway/bootstrap.js +200 -0
  86. package/lib/gateway/bootstrap.js.map +1 -0
  87. package/lib/gateway/index.d.ts +3 -0
  88. package/lib/gateway/index.d.ts.map +1 -0
  89. package/lib/gateway/index.js +3 -0
  90. package/lib/gateway/index.js.map +1 -0
  91. package/lib/gateway/middleware-setup.d.ts +12 -0
  92. package/lib/gateway/middleware-setup.d.ts.map +1 -0
  93. package/lib/gateway/middleware-setup.js +82 -0
  94. package/lib/gateway/middleware-setup.js.map +1 -0
  95. package/lib/host/adapter.d.ts +48 -0
  96. package/lib/host/adapter.d.ts.map +1 -0
  97. package/lib/host/adapter.js +127 -0
  98. package/lib/host/adapter.js.map +1 -0
  99. package/lib/humanlike/ENV_PROMPT.md +28 -0
  100. package/lib/humanlike/affinity.js +316 -0
  101. package/lib/humanlike/learn.js +343 -0
  102. package/lib/humanlike/life.js +899 -0
  103. package/lib/humanlike/mind.js +323 -0
  104. package/lib/humanlike/plugin.js +587 -0
  105. package/lib/humanlike/reach.js +119 -0
  106. package/lib/humanlike/real.js +276 -0
  107. package/lib/humanlike/rules.js +67 -0
  108. package/lib/humanlike/settings-api.js +159 -0
  109. package/lib/humanlike/settings.js +370 -0
  110. package/lib/humanlike/together.js +251 -0
  111. package/lib/identity/paths.js +27 -0
  112. package/lib/identity/persona.js +75 -0
  113. package/lib/identity/portrait.js +25 -0
  114. package/lib/identity/runtime.js +78 -0
  115. package/lib/index.d.ts +15 -0
  116. package/lib/index.js +117 -0
  117. package/lib/media/draft-tool.js +442 -0
  118. package/lib/media/draft-tool.js.bak-to-182027 +389 -0
  119. package/lib/media/media-cleaner.d.ts +19 -0
  120. package/lib/media/media-cleaner.d.ts.map +1 -0
  121. package/lib/media/media-cleaner.js +81 -0
  122. package/lib/media/media-cleaner.js.map +1 -0
  123. package/lib/media/say-tool.js +72 -0
  124. package/lib/media/send-file-tool.d.ts +12 -0
  125. package/lib/media/send-file-tool.d.ts.map +1 -0
  126. package/lib/media/send-file-tool.js +122 -0
  127. package/lib/media/send-file-tool.js.map +1 -0
  128. package/lib/media/send-media.d.ts +61 -0
  129. package/lib/media/send-media.d.ts.map +1 -0
  130. package/lib/media/send-media.js +104 -0
  131. package/lib/media/send-media.js.map +1 -0
  132. package/lib/media/vision-tool.d.ts +22 -0
  133. package/lib/media/vision-tool.d.ts.map +1 -0
  134. package/lib/media/vision-tool.js +288 -0
  135. package/lib/media/vision-tool.js.map +1 -0
  136. package/lib/middleware/attachment.d.ts +11 -0
  137. package/lib/middleware/attachment.d.ts.map +1 -0
  138. package/lib/middleware/attachment.js +30 -0
  139. package/lib/middleware/attachment.js.map +1 -0
  140. package/lib/middleware/question-answer.d.ts +10 -0
  141. package/lib/middleware/question-answer.d.ts.map +1 -0
  142. package/lib/middleware/question-answer.js +19 -0
  143. package/lib/middleware/question-answer.js.map +1 -0
  144. package/lib/model/index.d.ts +10 -0
  145. package/lib/model/index.d.ts.map +1 -0
  146. package/lib/model/index.js +9 -0
  147. package/lib/model/index.js.map +1 -0
  148. package/lib/model/model-resolver.d.ts +102 -0
  149. package/lib/model/model-resolver.d.ts.map +1 -0
  150. package/lib/model/model-resolver.js +206 -0
  151. package/lib/model/model-resolver.js.map +1 -0
  152. package/lib/model/prefs-store.d.ts +50 -0
  153. package/lib/model/prefs-store.d.ts.map +1 -0
  154. package/lib/model/prefs-store.js +215 -0
  155. package/lib/model/prefs-store.js.map +1 -0
  156. package/lib/model/settings-reader.d.ts +19 -0
  157. package/lib/model/settings-reader.d.ts.map +1 -0
  158. package/lib/model/settings-reader.js +76 -0
  159. package/lib/model/settings-reader.js.map +1 -0
  160. package/lib/model/types.d.ts +15 -0
  161. package/lib/model/types.d.ts.map +1 -0
  162. package/lib/model/types.js +5 -0
  163. package/lib/model/types.js.map +1 -0
  164. package/lib/resume-check.js +122 -0
  165. package/lib/resume-tool.js +29 -0
  166. package/lib/rules.js +57 -0
  167. package/lib/session/idle-evictor.d.ts +18 -0
  168. package/lib/session/idle-evictor.d.ts.map +1 -0
  169. package/lib/session/idle-evictor.js +31 -0
  170. package/lib/session/idle-evictor.js.map +1 -0
  171. package/lib/session/index.d.ts +9 -0
  172. package/lib/session/index.d.ts.map +1 -0
  173. package/lib/session/index.js +8 -0
  174. package/lib/session/index.js.map +1 -0
  175. package/lib/session/pick-agent.js +116 -0
  176. package/lib/session/session-id.d.ts +5 -0
  177. package/lib/session/session-id.d.ts.map +1 -0
  178. package/lib/session/session-id.js +15 -0
  179. package/lib/session/session-id.js.map +1 -0
  180. package/lib/session/session-manager.d.ts +138 -0
  181. package/lib/session/session-manager.d.ts.map +1 -0
  182. package/lib/session/session-manager.js +1157 -0
  183. package/lib/session/session-manager.js.bak-target +1081 -0
  184. package/lib/session/session-manager.js.bak-title-20261118 +1119 -0
  185. package/lib/session/session-manager.js.map +1 -0
  186. package/lib/session/types.d.ts +162 -0
  187. package/lib/session/types.d.ts.map +1 -0
  188. package/lib/session/types.js +2 -0
  189. package/lib/session/types.js.map +1 -0
  190. package/lib/setup/bind-routes.d.ts +78 -0
  191. package/lib/setup/bind-routes.d.ts.map +1 -0
  192. package/lib/setup/bind-routes.js +588 -0
  193. package/lib/setup/bind-routes.js.bak-join-163944 +761 -0
  194. package/lib/setup/bind-routes.js.map +1 -0
  195. package/lib/setup/binding-service.d.ts +86 -0
  196. package/lib/setup/binding-service.d.ts.map +1 -0
  197. package/lib/setup/binding-service.js +175 -0
  198. package/lib/setup/binding-service.js.map +1 -0
  199. package/lib/setup/index.d.ts +50 -0
  200. package/lib/setup/index.d.ts.map +1 -0
  201. package/lib/setup/index.js +163 -0
  202. package/lib/setup/index.js.map +1 -0
  203. package/lib/setup/persist.d.ts +42 -0
  204. package/lib/setup/persist.d.ts.map +1 -0
  205. package/lib/setup/persist.js +344 -0
  206. package/lib/setup/persist.js.map +1 -0
  207. package/lib/setup/presenters.d.ts +40 -0
  208. package/lib/setup/presenters.d.ts.map +1 -0
  209. package/lib/setup/presenters.js +84 -0
  210. package/lib/setup/presenters.js.map +1 -0
  211. package/lib/setup/qr-svg.d.ts +9 -0
  212. package/lib/setup/qr-svg.d.ts.map +1 -0
  213. package/lib/setup/qr-svg.js +33 -0
  214. package/lib/setup/qr-svg.js.map +1 -0
  215. package/lib/shared/bind-protocol.d.ts +42 -0
  216. package/lib/shared/bind-protocol.d.ts.map +1 -0
  217. package/lib/shared/bind-protocol.js +33 -0
  218. package/lib/shared/bind-protocol.js.map +1 -0
  219. package/lib/shared/dirs.d.ts +10 -0
  220. package/lib/shared/dirs.d.ts.map +1 -0
  221. package/lib/shared/dirs.js +20 -0
  222. package/lib/shared/dirs.js.map +1 -0
  223. package/lib/shared/http-body.js +43 -0
  224. package/lib/shared/index.d.ts +8 -0
  225. package/lib/shared/index.d.ts.map +1 -0
  226. package/lib/shared/index.js +8 -0
  227. package/lib/shared/index.js.map +1 -0
  228. package/lib/shared/json-file.js +34 -0
  229. package/lib/shared/orders.js +26 -0
  230. package/lib/shared/scope.d.ts +14 -0
  231. package/lib/shared/scope.d.ts.map +1 -0
  232. package/lib/shared/scope.js +12 -0
  233. package/lib/shared/scope.js.map +1 -0
  234. package/lib/shared/send-helper.d.ts +11 -0
  235. package/lib/shared/send-helper.d.ts.map +1 -0
  236. package/lib/shared/send-helper.js +13 -0
  237. package/lib/shared/send-helper.js.map +1 -0
  238. package/lib/shared/utils.d.ts +31 -0
  239. package/lib/shared/utils.d.ts.map +1 -0
  240. package/lib/shared/utils.js +228 -0
  241. package/lib/shared/utils.js.map +1 -0
  242. package/lib/tool-guard.js +74 -0
  243. package/lib/transport/attachment.d.ts +41 -0
  244. package/lib/transport/attachment.d.ts.map +1 -0
  245. package/lib/transport/attachment.js +191 -0
  246. package/lib/transport/attachment.js.map +1 -0
  247. package/lib/transport/chunker.d.ts +14 -0
  248. package/lib/transport/chunker.d.ts.map +1 -0
  249. package/lib/transport/chunker.js +78 -0
  250. package/lib/transport/chunker.js.map +1 -0
  251. package/lib/transport/deliverables.d.ts +20 -0
  252. package/lib/transport/deliverables.d.ts.map +1 -0
  253. package/lib/transport/deliverables.js +72 -0
  254. package/lib/transport/deliverables.js.map +1 -0
  255. package/lib/transport/events.d.ts +117 -0
  256. package/lib/transport/events.d.ts.map +1 -0
  257. package/lib/transport/events.js +112 -0
  258. package/lib/transport/events.js.map +1 -0
  259. package/lib/transport/inbound.d.ts +11 -0
  260. package/lib/transport/inbound.d.ts.map +1 -0
  261. package/lib/transport/inbound.js +511 -0
  262. package/lib/transport/inbound.js.map +1 -0
  263. package/lib/transport/index.d.ts +10 -0
  264. package/lib/transport/index.d.ts.map +1 -0
  265. package/lib/transport/index.js +10 -0
  266. package/lib/transport/index.js.map +1 -0
  267. package/lib/transport/msgid-cache.d.ts +23 -0
  268. package/lib/transport/msgid-cache.d.ts.map +1 -0
  269. package/lib/transport/msgid-cache.js +57 -0
  270. package/lib/transport/msgid-cache.js.map +1 -0
  271. package/lib/transport/notify.js +147 -0
  272. package/lib/transport/outbound-buffer.d.ts +42 -0
  273. package/lib/transport/outbound-buffer.d.ts.map +1 -0
  274. package/lib/transport/outbound-buffer.js +68 -0
  275. package/lib/transport/outbound-buffer.js.map +1 -0
  276. package/lib/transport/outbound.d.ts +42 -0
  277. package/lib/transport/outbound.d.ts.map +1 -0
  278. package/lib/transport/outbound.js +183 -0
  279. package/lib/transport/outbound.js.map +1 -0
  280. package/lib/transport/reply-limiter.d.ts +31 -0
  281. package/lib/transport/reply-limiter.d.ts.map +1 -0
  282. package/lib/transport/reply-limiter.js +50 -0
  283. package/lib/transport/reply-limiter.js.map +1 -0
  284. package/lib/transport/reply-target.d.ts +32 -0
  285. package/lib/transport/reply-target.d.ts.map +1 -0
  286. package/lib/transport/reply-target.js +64 -0
  287. package/lib/transport/reply-target.js.map +1 -0
  288. package/lib/transport/streaming-writer.d.ts +55 -0
  289. package/lib/transport/streaming-writer.d.ts.map +1 -0
  290. package/lib/transport/streaming-writer.js +122 -0
  291. package/lib/transport/streaming-writer.js.map +1 -0
  292. package/lib/transport/tool-presenter.d.ts +37 -0
  293. package/lib/transport/tool-presenter.d.ts.map +1 -0
  294. package/lib/transport/tool-presenter.js +116 -0
  295. package/lib/transport/tool-presenter.js.map +1 -0
  296. package/lib/turn-check.js +85 -0
  297. package/lib/types.d.ts +39 -0
  298. package/lib/types.js +5 -0
  299. package/locale/en.json +6 -0
  300. package/locale/zh.json +6 -0
  301. package/package.json +127 -4
package/README.md CHANGED
@@ -1,3 +1,282 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <img width="120" src="https://img.shields.io/badge/🤖-QQ_Bot-blue?style=for-the-badge" alt="QQ Bot" />
4
+
5
+ **把 QQ 接成 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的聊天渠道:私聊、群聊、语音、图片、文件都能收发。**
6
+
7
+ [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
8
+ [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
9
+
10
+ **[English](./README_EN.md) | 简体中文**
11
+
12
+ </div>
13
+
14
+ > **这是个人 fork**:[tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot) 的深度改造版,不是官方包。上游提供 QQ 接入的基本骨架,这个 fork 在上面加了一整套「陪伴型机器人」的东西(见下)。装法、配置项、命令都沿用上游,文档里没特别说明的地方以上游为准。
15
+ >
16
+ > 仓库里只有编译后的 `lib/`(上游发布方式如此),没有 TypeScript 源码,所以不能在这里 `pnpm build`。
17
+
18
+ ## 这个 fork 多了什么
19
+
20
+ - **人味(humanlike)**:交情账、共同经历、学习笔记、作息状态、惦记清单、只读观察,7 组工具 + 系统提示里的状态段,让 bot 有自己的关系和时间感,不是每轮重置的问答机。
21
+ - **长期记忆(fishmemory)**:把对话转录成笔记(规矩 / 教训 / 事实 / 经过 / 人 / 待办),每轮现读索引,需要细节时再检索原话。
22
+ - **闹钟**:到某个钟点把自己叫醒去做一件具体的事(和定时任务分开)。
23
+ - **重启接话**:宿主重启后不再往旧会话里灌消息,改成给一个 `qq_resume_check` 工具,让模型自己决定要不要接着上一轮说话。
24
+ - **人设与规则可覆盖**:`persona.md` / `rules.md` / `portrait.md` 三个文件放在数据目录里,改了立刻生效,不用动代码。
25
+ - **表情包(memes)**:本机图库按情绪分桶,能按描述和标签挑图,也能当表情发出去;设置页里有「表情包」页签直接管理(看图、改描述标签、换目录、清失效)。
26
+ - **配套插件**:`dsh-day`(自己定起床点、开单收单)、`dsh-map`(出门、回家、到点推一次)是另外两个独立插件,不在这一个仓库里。
27
+ - **设置页四个页签**:机器人(连接与运行参数)/ 人设(人设、画像、回话规则)/ 人味 / 表情包,样式统一。
28
+
29
+ ## 来源与授权
30
+
31
+ 这个仓库不是从零写的,几块东西各有出处,按 MIT 协议保留原许可:
32
+
33
+ | 部分 | 来源 | 许可 |
34
+ |---|---|---|
35
+ | QQ 接入骨架(消息收发、一对多会话、工具闸门) | [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot) | MIT |
36
+ | 人味(humanlike,7 组工具 + 状态段) | npm [`cortico-world-humanlike-alont1`](https://www.npmjs.com/package/cortico-world-humanlike-alont1) v0.2.2-rc.1,作者 ALonT1 | MIT |
37
+ | 长期记忆、闹钟、重启接话、表情包、设置页页签 | 本 fork 新增 | 同本项目 |
38
+
39
+ 搬过来的部分基本保持原样,只把宿主接口换成了 dsh 的 `tools.register` 与系统提示段。如果你要用的是干净的原始实现,直接去上面两个上游。
40
+
41
+ ## 我开始用它之前
42
+
43
+ 1. 你需要一个 QQ 机器人(QQ 开放平台注册,拿到 `appId` 和 `appSecret`)。
44
+ 2. 这台机器上要装好 DeepSeek Harness。
45
+ 3. 凭据只写进 dsh profile 的 `cordis.patch.yml`,不要提交进仓库。
46
+
47
+ ## 架构
48
+
49
+ ```
50
+ QQ 用户 → QQ WebSocket → dsh-qqbot → ctx.agents → dsh agent loop → LLM
51
+ ↑ │
52
+ └── session/event ──────────┘
53
+ (assistant reply → QQ sendMarkdown)
54
+ ```
55
+
56
+ ## 安装
57
+
58
+ 这个 fork 的包名是 `dsh-qqbot-plus`,安装用的是 GitHub 直连:`github:i-Fyn/dsh-qqbot-plus`。
59
+ 不要装 `@tencent-connect/dsh-qqbot` —— 那是上游原始版,没有这里加的人味、记忆、表情包。
60
+
61
+ ### 方式一:桌面版安装(推荐)
62
+
63
+ 无需命令行,全程在应用内完成:
64
+
65
+ 1. **安装**:左侧栏点击「插件」→「添加插件」→ 输入 `github:i-Fyn/dsh-qqbot-plus` → 安装并立即启动
66
+
67
+ <img src="./assets/docs/install.png" alt="端内添加插件" width="560" />
68
+
69
+ 2. **连接**:左下角头像 → 设置 →「QQ 机器人」→ 手机 QQ 扫码连接
70
+
71
+ <img src="./assets/docs/setting.png" alt="设置页扫码连接" width="560" />
72
+
73
+ 扫码成功后凭据自动保存,后续启动无需再次扫码。
74
+
75
+ ### 方式二:手动执行
76
+
77
+ ```bash
78
+ # 安装到 profile
79
+ npx @deepseek-ai/dsh plugin --profile qqbot add github:i-Fyn/dsh-qqbot-plus
80
+
81
+ # 启动
82
+ npx @deepseek-ai/dsh --profile qqbot
83
+ ```
84
+
85
+ 首次启动时,插件检测到凭据未配置会自动进入扫码引导:终端输出二维码 → 手机 QQ 扫码绑定 → 凭据自动保存到 profile,后续启动无需再次扫码。
86
+
87
+ 无端内绑定页的环境(如纯 CLI)可设置 `QQBOT_BIND_OPEN_BROWSER=1`,额外拉起系统浏览器扫码页作为降级通道。
88
+
89
+ <img src="./assets/docs/qrcode.png" alt="二维码扫码示意图" width="280" />
90
+
91
+ > **装到一半可能卡在 `sharp`**:发表情图时用 `sharp` 缩尺寸,它是可选依赖。pnpm 默认不执行依赖的构建脚本,命令行安装会报
92
+ > `ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: sharp@0.34.5` 并中断。按它打印的那一行,在 profile 的
93
+ > `pnpm-workspace.yaml` 末尾加上下面的内容,再跑一次同一条安装命令就过了:
94
+ >
95
+ > ```yaml
96
+ > allowBuilds:
97
+ > sharp: true
98
+ > ```
99
+ >
100
+ > 不加也能装(跳过 sharp),只是发出去的表情图不会被缩到长边 360。
101
+
102
+ ### 方式三:本地目录安装
103
+
104
+ ```bash
105
+ git clone https://github.com/i-Fyn/dsh-qqbot-plus /path/to/dsh-qqbot-plus
106
+
107
+ # 装到 profile(指向目录就行,仓库里已经是编译好的 lib/,不用构建)
108
+ npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot-plus
109
+
110
+ # 启动
111
+ npx @deepseek-ai/dsh --profile qqbot
112
+ ```
113
+
114
+ ## 配置项
115
+
116
+ | 配置 | 类型 | 默认值 | 说明 |
117
+ |------|------|--------|------|
118
+ | `appId` | string | **必填** | QQ Bot AppID(或通过 `QQBOT_APPID` 环境变量) |
119
+ | `appSecret` | string | **必填** | QQ Bot AppSecret(或通过 `QQBOT_SECRET` 环境变量) |
120
+ | `provider` | string | `deepseek-official` | LLM 提供商名称 |
121
+ | `model` | string | `deepseek-chat` | 模型名称 |
122
+ | `preset` | string | - | Agent preset id |
123
+ | `cwd` | string | `process.cwd()` | Agent 工作目录 |
124
+ | `requireMention` | boolean | `true` | 群聊是否需要 @bot 才触发 |
125
+ | `groupPrompt` | string | - | 群聊额外 system prompt |
126
+ | `directPrompt` | string | - | 私聊额外 system prompt |
127
+ | `textChunkLimit` | number | `4500` | 单条消息最大字符数 |
128
+ | `streaming` | boolean | `true` | 是否启用流式输出(群聊始终不启用) |
129
+ | `sessionIdleTimeout` | number | `1800000` | 会话闲置超时(ms),默认 30 分钟 |
130
+ | `processingTimeoutMs` | number | `1800000` | 处理超时(ms),超时中断当前 LLM 调用 |
131
+ | `maxQueue` | number | `20` | 并发队列最大长度 |
132
+ | `historyLimit` | number | `10` | 群历史缓冲条数 |
133
+ | `askTimeoutMs` | number | `300000` | 待答问题超时(ms),默认 5 分钟(ask_user_question) |
134
+ | `showToolResults` | boolean | `false` | 是否展示工具调用成功结果(错误始终展示) |
135
+ | `debug` | boolean | `false` | 调试模式 |
136
+
137
+ ### 访问控制(access)
138
+
139
+ | 配置 | 类型 | 默认值 | 说明 |
140
+ |------|------|--------|------|
141
+ | `access.c2cMode` | `open`/`allowlist`/`disabled` | `open` | 私聊访问模式 |
142
+ | `access.c2cAllow` | string[] | `[]` | 私聊白名单(user openid) |
143
+ | `access.groupMode` | `open`/`allowlist`/`disabled` | `open` | 群聊访问模式 |
144
+ | `access.groupAllow` | string[] | `[]` | 群聊白名单(group openid) |
145
+
146
+ ### 富媒体理解(media)
147
+
148
+ | 配置 | 类型 | 默认值 | 说明 |
149
+ |------|------|--------|------|
150
+ | `media.enabled` | boolean | `true` | 是否启用富媒体理解(图片/视频下载 + 工具分析) |
151
+ | `media.maxMB` | number | `200` | 富媒体下载大小上限(MB) |
152
+ | `media.ttlHours` | number | `24` | 富媒体存活时长(小时),0=永不过期 |
153
+
154
+ ### 视觉理解(vision)
155
+
156
+ | 配置 | 类型 | 默认值 | 说明 |
157
+ |------|------|--------|------|
158
+ | `vision.enabled` | boolean | `false` | 是否启用视觉理解(qqbot_describe_image 工具) |
159
+ | `vision.provider` | string | - | 视觉模型 provider(如 pi-ai) |
160
+ | `vision.model` | string | - | 视觉模型 id(如 qwen-vl-max) |
161
+ | `vision.maxBytes` | number | `10MB` | 图片字节上限 |
162
+ | `vision.maxTokens` | number | `1024` | 输出 token 上限 |
163
+ | `vision.timeoutMs` | number | `120000` | 视觉调用超时(ms) |
164
+
165
+ ### 附件发送(sendFile)
166
+
167
+ | 配置 | 类型 | 默认值 | 说明 |
168
+ |------|------|--------|------|
169
+ | `sendFile.restrictPaths` | boolean | `true` | 是否启用路径白名单(仅 media + cwd + extraRoots) |
170
+ | `sendFile.extraRoots` | string[] | `[]` | 额外允许访问的根目录 |
171
+
172
+ ## 内置命令
173
+
174
+ | 命令 | 说明 |
175
+ |------|------|
176
+ | `/compact` | 压缩会话历史(摘要替换旧记录,保留上下文) |
177
+ | `/model` | 查看或切换模型 |
178
+ | `/preset` | 查看或切换 agent preset(新会话生效) |
179
+ | `/stop` | 中止当前生成 |
180
+ | `/bot-ping` | 网络延迟检测(返回传输与处理耗时) |
181
+ | `/bot-version` | 查看版本信息 |
182
+ | `/bot-status` | 查看当前会话状态 |
183
+ | `/bot-help` | 查看所有指令 |
184
+
185
+ ## 核心模块
186
+
187
+ 下面是上游的源码结构,用来说明代码怎么分的。本仓库只带编译后的 `lib/`,同名的文件后缀是 `.js` 而不是 `.ts`。
188
+
189
+ ```
190
+ src/
191
+ ├── index.ts # Cordis 插件入口(async apply)
192
+ ├── config.ts # 配置 Schema
193
+ ├── types.ts # 全局类型定义
194
+ ├── setup/ # 凭据绑定(扫码)
195
+ │ ├── index.ts # 绑定编排(ensureCredentials)
196
+ │ ├── binding-service.ts # 扫码状态机(宿主内唯一事实源)
197
+ │ ├── bind-routes.ts # 端内绑定页路由(/qqbot/im-qqbot/bind)
198
+ │ ├── presenters.ts # 呈现策略(终端/浏览器降级)
199
+ │ ├── qr-svg.ts # 二维码 SVG 渲染(宿主侧)
200
+ │ └── persist.ts # 凭据写入 cordis.patch.yml
201
+ ├── client/ # 浏览器半边(dsh.client Web Bundle)
202
+ │ ├── index.ts # 侧栏 Tab 注册 + 待绑定自动引导
203
+ │ └── bind-page.ts # 端内绑定页(二维码 + 状态轮询)
204
+ ├── gateway/ # 网关装配
205
+ │ ├── bootstrap.ts # 启动装配(监听 session/event 等)
206
+ │ └── middleware-setup.ts # 中间件链配置
207
+ ├── transport/ # 传输层
208
+ │ ├── inbound.ts # QQ 入站消息 → agent.followup()
209
+ │ ├── outbound.ts # session/event → QQ sendMarkdown
210
+ │ ├── outbound-buffer.ts # 流式缓冲
211
+ │ ├── streaming-writer.ts # 流式写入
212
+ │ ├── reply-target.ts # 回复目标解析
213
+ │ ├── msgid-cache.ts # 被动回复 msgid 缓存
214
+ │ ├── reply-limiter.ts # 被动回复限流
215
+ │ ├── tool-presenter.ts # 工具调用展示
216
+ │ └── chunker.ts # Markdown 文本切分
217
+ ├── session/ # 会话管理层
218
+ │ ├── session-manager.ts # QQ peer → Agent 映射
219
+ │ └── idle-evictor.ts # 闲置回收
220
+ ├── model/ # 模型路由层
221
+ │ ├── model-resolver.ts # 路由解析
222
+ │ ├── prefs-store.ts # per-peer 偏好持久化
223
+ │ └── settings-reader.ts # settings.yaml 只读
224
+ ├── features/ # 交互特性
225
+ │ ├── question-channel.ts # ask_user_question 问答通道
226
+ │ ├── approval-channel.ts # approval 审批确认通道
227
+ │ └── answer-parser.ts # 答案解析
228
+ ├── media/ # 多媒体
229
+ │ ├── vision-tool.ts # 图片视觉理解
230
+ │ ├── send-file-tool.ts # 发送本地文件
231
+ │ └── media-cleaner.ts # 媒体 TTL 清理
232
+ ├── middleware/ # 中间件
233
+ │ ├── question-answer.ts # 问答答案处理
234
+ │ └── attachment.ts # 附件处理
235
+ ├── shared/ # 共享工具
236
+ │ ├── utils.ts # 通用函数
237
+ │ ├── scope.ts # scope/peer 提取
238
+ │ └── send-helper.ts # 分块发送
239
+ └── commands/ # 斜杠命令
240
+ ```
241
+
242
+ ## 会话路由
243
+
244
+ sessionKey: `qqbot:${appId}:${scope}:${peerId}`,新会话铸造 UUID 会话 id 并持久化到 `model-prefs.json`,重启后按持久化 id 恢复;0.5.x 老会话按原派生 id 沿用。
245
+
246
+ 解析策略:进程内复用 → 持久化恢复 → 全新创建。
247
+
248
+ ## 设计原则
249
+
250
+ - **纯 Cordis 插件** — 遵循 dsh "Plugins, not loop changes" 原则
251
+ - **声明式依赖** — `inject = ['agents']`,不直接耦合其他插件
252
+ - **会话隔离** — 每个 QQ 私聊用户/群聊各一个独立 Agent
253
+ - **Preset 支持** — 可通过 `agent-presets` 服务挂载预设(工具集、prompt 等)
254
+ - **闲置回收** — 超时自动 dispose Agent,防止内存泄漏
255
+ - **Markdown 输出** — 回复以 Markdown 格式发送,支持代码块/表格感知切分
256
+ - **图片理解** — 支持 `qqbot_describe_image` 视觉理解,可分析用户发送的图片
257
+ - **附件发送** — 支持 `qqbot_send_file` 将本地文件发送给用户(默认启用路径白名单)
258
+ - **问答互动** — 支持 `ask_user_question`,单选生成内联按钮(点一个其余变灰)、多选回复编号,逐题推进 + 问题级超时
259
+ - **操作确认** — 支持 `approval/request`,关键操作通过「允许/拒绝」按钮请求用户确认
260
+
261
+ ## 本地开发(仅适用于有源码的完整仓库)
262
+
263
+ > 本仓库只带编译产物 `lib/`,下面这些命令跑不通,保留是因为上游文档这么写。
264
+
265
+ ```bash
266
+ # 安装依赖
267
+ pnpm install
268
+
269
+ # 构建
270
+ pnpm build
271
+
272
+ # 开发模式(watch)
273
+ pnpm dev
274
+
275
+ # 用 --patch 方式调试
276
+ export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
277
+ npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
278
+ ```
279
+
280
+ ## License
281
+
282
+ [MIT](./LICENSE)
package/README_EN.md ADDED
@@ -0,0 +1,248 @@
1
+ <div align="center">
2
+
3
+ <img width="120" src="https://img.shields.io/badge/🤖-QQ_Bot-blue?style=for-the-badge" alt="QQ Bot" />
4
+
5
+ **A QQ Bot plugin for [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (dsh), connecting DeepSeek AI assistants to QQ private and group chats.**
6
+
7
+ [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
8
+ [![GitHub stars](https://img.shields.io/github/stars/i-Fyn/dsh-qqbot-plus)](https://github.com/i-Fyn/dsh-qqbot-plus)
9
+ [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
10
+
11
+ <br/>
12
+
13
+ **[简体中文](./README.md) | English**
14
+
15
+ Scan to join the QQ group / channel
16
+
17
+ <table>
18
+ <tr>
19
+ <td align="center" width="50%"><img src="./assets/docs/qqgroup.jpg" height="360" alt="QQ Group QR Code" /><br /><b>QQ Developer Group</b><br /><sub>Group 1: 1032635674 · Group 2: 1056948758</sub></td>
20
+ <td align="center" width="50%"><img src="./assets/docs/qqchannel.jpg" height="360" alt="QQ Channel QR Code" /><br /><b>QQ Developer Channel</b><br /><sub>Channel ID: 20dnumts4z</sub></td>
21
+ </tr>
22
+ </table>
23
+
24
+ </div>
25
+
26
+ ## Architecture
27
+
28
+ ```
29
+ QQ User → QQ WebSocket → dsh-qqbot → ctx.agents → dsh agent loop → LLM
30
+ ↑ │
31
+ └── session/event ──────────┘
32
+ (assistant reply → QQ sendMarkdown)
33
+ ```
34
+
35
+ ## Installation
36
+
37
+ This fork's package name is `dsh-qqbot-plus`; install it straight from GitHub: `github:i-Fyn/dsh-qqbot-plus`.
38
+ Do not install `@tencent-connect/dsh-qqbot` — that is the upstream original without the humanlike, memory and meme features added here.
39
+
40
+ ### Method 1: Desktop install (recommended)
41
+
42
+ No command line needed — everything happens inside the app:
43
+
44
+ 1. **Install**: click "Plugins" in the left sidebar → "Add plugin" → enter `github:i-Fyn/dsh-qqbot-plus` → install and start now
45
+
46
+ <img src="./assets/docs/install.png" alt="In-app plugin install" width="560" />
47
+
48
+ 2. **Connect**: avatar at the bottom-left → Settings → "QQ Bots" → scan the QR code with mobile QQ
49
+
50
+ <img src="./assets/docs/setting.png" alt="Settings QR binding" width="560" />
51
+
52
+ Credentials are saved automatically after the scan; later launches need no re-scan.
53
+
54
+ ### Method 2: Manual
55
+
56
+ ```bash
57
+ # Add to a profile
58
+ npx @deepseek-ai/dsh plugin --profile qqbot add github:i-Fyn/dsh-qqbot-plus
59
+
60
+ # Start
61
+ npx @deepseek-ai/dsh --profile qqbot
62
+ ```
63
+
64
+ On first launch, the plugin detects missing credentials and automatically starts the QR flow: a QR code is printed in the terminal → scan it with the QQ mobile app → credentials are saved to the profile, so subsequent launches require no re-scan.
65
+
66
+ In environments without the in-app binding page (pure CLI), set `QQBOT_BIND_OPEN_BROWSER=1` to additionally open a browser QR page as a fallback.
67
+
68
+ <img src="./assets/docs/qrcode.png" alt="QR code scan example" width="280" />
69
+
70
+ > **It may stall on `sharp`**: `sharp` is an optional dependency used to downscale meme images. pnpm does not run dependency
71
+ > build scripts by default, so a CLI install reports `ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: sharp@0.34.5` and stops.
72
+ > Add the following to the profile's `pnpm-workspace.yaml` and re-run the same install command:
73
+ >
74
+ > ```yaml
75
+ > allowBuilds:
76
+ > sharp: true
77
+ > ```
78
+ >
79
+ > It still installs without this (sharp is skipped), but outgoing meme images are not downscaled to a 360px long edge.
80
+
81
+ ### Method 3: Local directory
82
+
83
+ ```bash
84
+ git clone https://github.com/i-Fyn/dsh-qqbot-plus /path/to/dsh-qqbot-plus
85
+
86
+ # Add to a profile — point at the directory; lib/ is already built, no build step
87
+ npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot-plus
88
+
89
+ # Start
90
+ npx @deepseek-ai/dsh --profile qqbot
91
+ ```
92
+
93
+ ## Configuration
94
+
95
+ | Config | Type | Default | Description |
96
+ |------|------|--------|------|
97
+ | `appId` | string | **required** | QQ Bot AppID (or via `QQBOT_APPID` env var) |
98
+ | `appSecret` | string | **required** | QQ Bot AppSecret (or via `QQBOT_SECRET` env var) |
99
+ | `provider` | string | `deepseek-official` | LLM provider name |
100
+ | `model` | string | `deepseek-chat` | Model name |
101
+ | `preset` | string | - | Agent preset id |
102
+ | `cwd` | string | `process.cwd()` | Agent working directory |
103
+ | `requireMention` | boolean | `true` | Whether group messages require @bot to trigger |
104
+ | `groupPrompt` | string | - | Extra system prompt for group chats |
105
+ | `directPrompt` | string | - | Extra system prompt for direct chats |
106
+ | `textChunkLimit` | number | `4500` | Max chars per message |
107
+ | `streaming` | boolean | `true` | Enable streaming output (always disabled in groups) |
108
+ | `sessionIdleTimeout` | number | `1800000` | Session idle timeout (ms), default 30 min |
109
+ | `processingTimeoutMs` | number | `1800000` | Processing timeout (ms), aborts the current LLM call |
110
+ | `maxQueue` | number | `20` | Max concurrent queue length |
111
+ | `historyLimit` | number | `10` | Group history buffer size |
112
+ | `askTimeoutMs` | number | `300000` | Question timeout (ms), default 5 min (ask_user_question) |
113
+ | `showToolResults` | boolean | `false` | Show successful tool-call results (errors always shown) |
114
+ | `debug` | boolean | `false` | Debug mode |
115
+
116
+ ### Access control (access)
117
+
118
+ | Config | Type | Default | Description |
119
+ |------|------|--------|------|
120
+ | `access.c2cMode` | `open`/`allowlist`/`disabled` | `open` | Direct-chat access mode |
121
+ | `access.c2cAllow` | string[] | `[]` | Direct-chat allowlist (user openid) |
122
+ | `access.groupMode` | `open`/`allowlist`/`disabled` | `open` | Group access mode |
123
+ | `access.groupAllow` | string[] | `[]` | Group allowlist (group openid) |
124
+
125
+ ### Rich media (media)
126
+
127
+ | Config | Type | Default | Description |
128
+ |------|------|--------|------|
129
+ | `media.enabled` | boolean | `true` | Enable rich media understanding (image/video download + tool analysis) |
130
+ | `media.maxMB` | number | `200` | Max download size (MB) |
131
+ | `media.ttlHours` | number | `24` | Media lifetime (hours), 0 = never expire |
132
+
133
+ ### Vision (vision)
134
+
135
+ | Config | Type | Default | Description |
136
+ |------|------|--------|------|
137
+ | `vision.enabled` | boolean | `false` | Enable vision (qqbot_describe_image tool) |
138
+ | `vision.provider` | string | - | Vision model provider (e.g. pi-ai) |
139
+ | `vision.model` | string | - | Vision model id (e.g. qwen-vl-max) |
140
+ | `vision.maxBytes` | number | `10MB` | Max image bytes |
141
+ | `vision.maxTokens` | number | `1024` | Max output tokens |
142
+ | `vision.timeoutMs` | number | `120000` | Vision call timeout (ms) |
143
+
144
+ ### File sending (sendFile)
145
+
146
+ | Config | Type | Default | Description |
147
+ |------|------|--------|------|
148
+ | `sendFile.restrictPaths` | boolean | `true` | Enable path allowlist (media + cwd + extraRoots only) |
149
+ | `sendFile.extraRoots` | string[] | `[]` | Extra allowed root directories |
150
+
151
+ ## Built-in Commands
152
+
153
+ | Command | Description |
154
+ |------|------|
155
+ | `/compact` | Compact session history (replace old records with a summary) |
156
+ | `/model` | View or switch model |
157
+ | `/preset` | View or switch agent preset (applies to new sessions) |
158
+ | `/stop` | Abort the current generation |
159
+ | `/bot-ping` | Network latency test (transport & processing time) |
160
+ | `/bot-version` | View version info |
161
+ | `/bot-status` | View current session status |
162
+ | `/bot-help` | View all commands |
163
+
164
+ ## Core Modules
165
+
166
+ ```
167
+ src/
168
+ ├── index.ts # Cordis plugin entry (async apply)
169
+ ├── config.ts # Config schema
170
+ ├── types.ts # Global types
171
+ ├── setup.ts # Credential binding (QR)
172
+ ├── gateway/ # Gateway assembly
173
+ │ ├── bootstrap.ts # Startup wiring (session/event listeners, etc.)
174
+ │ └── middleware-setup.ts # Middleware chain config
175
+ ├── transport/ # Transport layer
176
+ │ ├── inbound.ts # QQ inbound message → agent.followup()
177
+ │ ├── outbound.ts # session/event → QQ sendMarkdown
178
+ │ ├── outbound-buffer.ts # Streaming buffer
179
+ │ ├── streaming-writer.ts # Streaming writer
180
+ │ ├── reply-target.ts # Reply target resolution
181
+ │ ├── msgid-cache.ts # Passive reply msgid cache
182
+ │ ├── reply-limiter.ts # Passive reply rate limiter
183
+ │ ├── tool-presenter.ts # Tool-call presentation
184
+ │ └── chunker.ts # Markdown chunking
185
+ ├── session/ # Session management
186
+ │ ├── session-manager.ts # QQ peer → Agent mapping
187
+ │ └── idle-evictor.ts # Idle eviction
188
+ ├── model/ # Model routing
189
+ │ ├── model-resolver.ts # Route resolution
190
+ │ ├── prefs-store.ts # Per-peer preference persistence
191
+ │ └── settings-reader.ts # settings.yaml read-only
192
+ ├── features/ # Interaction features
193
+ │ ├── question-channel.ts # ask_user_question Q&A channel
194
+ │ ├── approval-channel.ts # approval confirmation channel
195
+ │ └── answer-parser.ts # Answer parsing
196
+ ├── media/ # Media
197
+ │ ├── vision-tool.ts # Image vision understanding
198
+ │ ├── send-file-tool.ts # Send local files
199
+ │ └── media-cleaner.ts # Media TTL cleanup
200
+ ├── middleware/ # Middleware
201
+ │ ├── question-answer.ts # Q&A answer handling
202
+ │ └── attachment.ts # Attachment handling
203
+ ├── shared/ # Shared utilities
204
+ │ ├── utils.ts # Common helpers
205
+ │ ├── scope.ts # scope/peer extraction
206
+ │ └── send-helper.ts # Chunked send
207
+ └── commands/ # Slash commands
208
+ ```
209
+
210
+ ## Session Routing
211
+
212
+ sessionKey: `qqbot:${appId}:${scope}:${peerId}`; a UUID session id is minted for new sessions and persisted to `model-prefs.json`, resuming by the persisted id after restarts; pre-0.6 sessions keep their originally derived ids.
213
+
214
+ Resolution strategy: in-process reuse → persisted resume → fresh create.
215
+
216
+ ## Design Principles
217
+
218
+ - **Pure Cordis plugin** — follows the dsh "Plugins, not loop changes" principle
219
+ - **Declarative dependencies** — `inject = ['agents']`, no direct coupling to other plugins
220
+ - **Session isolation** — one independent Agent per QQ direct user / group
221
+ - **Preset support** — mount presets (toolkits, prompts, etc.) via the `agent-presets` service
222
+ - **Idle eviction** — auto-dispose Agents on timeout to prevent memory leaks
223
+ - **Markdown output** — replies sent as Markdown with code-block/table-aware chunking
224
+ - **Image understanding** — supports `qqbot_describe_image` vision to analyze images sent by users
225
+ - **File sending** — supports `qqbot_send_file` to send local files to users (path allowlist enabled by default)
226
+ - **Question interaction** — supports `ask_user_question` with inline keyboard buttons (mutually exclusive) or numbered replies, one question at a time with timeout
227
+ - **Approval confirmation** — supports `approval/request` to ask for user confirmation on critical actions via allow/deny buttons
228
+
229
+ ## Local Development
230
+
231
+ ```bash
232
+ # Install dependencies
233
+ pnpm install
234
+
235
+ # Build
236
+ pnpm build
237
+
238
+ # Dev mode (watch)
239
+ pnpm dev
240
+
241
+ # Debug via --patch
242
+ export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
243
+ npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml
244
+ ```
245
+
246
+ ## License
247
+
248
+ [MIT](./LICENSE)