dsh-qqchat 0.2.1 → 0.2.3

package/README.en.md

@@ -6,7 +6,8 @@
 
 <p>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
-  <img src="https://img.shields.io/badge/DSH-Plugin-6f42c1.svg" alt="DSH Plugin">
+  <img src="https://img.shields.io/badge/DSH-0.1.1--rc.2-6f42c1.svg" alt="DSH 0.1.1-rc.2">
+  <img src="https://img.shields.io/badge/QQChat-0.2.3-2ea44f.svg" alt="QQChat 0.2.3">
   <img src="https://img.shields.io/badge/TypeScript-5.x-3178c6.svg" alt="TypeScript">
 </p>
 
@@ -17,6 +18,8 @@
 
 <p><em>Chat in QQ, then view the complete Session, memory and tool activity in DSH Web.</em></p>
 
+<p>This release is verified against DSH <code>0.1.1-rc.2</code>. Install the plugin as-is; no DSH source patch or rebuild is required.</p>
+
 `dsh-qqchat` is an official QQ Bot plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness). It maps QQ groups and direct chats to ordinary DSH Sessions and uses DSH's native Conversation, Agent, command and tool surfaces.
 
 > This is a Vibe Coding project, so code quality and engineering completeness may need improvement. If you find a problem or have a better implementation idea, please open an [Issue](https://github.com/Coffeiz/dsh-qqchat/issues) or submit a [Pull Request](https://github.com/Coffeiz/dsh-qqchat/pulls).
@@ -36,12 +39,13 @@
 | Message formats | Smart, Markdown or Plain compatibility | Group and direct-chat formats are configured separately; groups default to Plain compatibility |
 | Direct-chat streaming | Optionally uses QQ's official streaming message API for private chats | Private chats only; Plain compatibility disables it automatically; some clients may not display streaming |
 | Quotes and mentions | Preserves quoted messages and resolves QQ mentions to display names | Stable IDs remain in metadata |
-| Memory system | Stores group, member and direct-user memory | Can be disabled; disabling does not delete existing memory |
+| Memory system | Stores group, member and direct-user memory; user memory can be reused across groups under the same Bot | Group relationships and group events stay scoped; can be disabled |
 | Memory reflection | Converts recent daily notes into long-term memory | Runs asynchronously after idle or batch thresholds |
 | Media and file permissions | Separately controls receiving media, reading attachments, and regular tools | Owner and direct chats are unrestricted by default |
-| Tool permissions | Separately controls whether group members may use regular Agent tools | Owner is matched by stable user ID |
+| Permission management | Separately controls group-member tools, media reading and file receiving | Owner is matched by stable user ID |
 | Native DSH commands | Runs `/compact`, `/goal`, `/plan`, `/qqmodel`, `/qqstatus` and more directly from QQ | Commands do not go through the model; `/qqhelp` lists the full set |
 | Native DSH UI | Uses the normal Session list, Conversation surface and composer styling | QQ Sessions remain ungrouped in DSH |
+| Session presets | Each QQ Session can use DSH's native Agent Preset mechanism | The plugin default applies only to new Sessions; a Session's own selection is persisted |
 | Diagnostics | Shows plugin logs in Settings | Useful for connection and delivery troubleshooting |
 
 ## How to use
@@ -68,7 +72,7 @@
     <td width="50%" valign="top">
       <img src="./docs/assets/记忆系统.jpg" width="100%" alt="QQ Chat memory system">
       <h3>Memory system</h3>
-      <p>The plugin maintains separate memory for groups, members and direct users. Member memory supports profiles, group nicknames, historical nicknames, behavior patterns and long-term notes; recent messages are organized asynchronously. Memory is refreshed as Session context when needed, and can be disabled without deleting stored data.</p>
+      <p>The plugin maintains separate memory for groups, members and direct users. Under the same Bot, user memory is reusable across groups by stable user ID; group relationships and group events remain scoped to their original group. Member memory supports profiles, group nicknames, historical nicknames, behavior patterns and long-term notes; recent messages are organized asynchronously. Memory is refreshed as Session context when needed, and can be disabled without deleting stored data.</p>
     </td>
   </tr>
 </table>
@@ -145,7 +149,7 @@ Groups default to Plain compatibility format. Group and direct-chat formats can
 
 ## Commands
 
-Messages beginning with `/` are handled directly by the command system and are not sent to the model. Native DSH commands keep their original names; QQChat commands use the `qq` prefix. In a group, write `@Bot /help` or `@Bot /qqhelp`.
+Messages beginning with `/` are handled directly by the command system and are not sent to the model. Native DSH commands keep their original names; QQChat commands use the `qq` prefix. In a group, write `@Bot /qqhelp`.
 
 | Command | Purpose |
 | --- | --- |
@@ -153,6 +157,7 @@ Messages beginning with `/` are handled directly by the command system and are n
 | `/qqnew`, `/qqreset`, `/qqclear` | Keep the old Session and start a new one on the next message |
 | `/compact` | Compact older conversation history |
 | `/qqmodel [provider/]model` | Show or switch the current Session model |
+| `/qqpreset [preset]` | List or switch the Agent Preset for the current blank Session; start a new Session after conversation begins |
 | `/qqstop` | Stop the current generation |
 | `/qqstatus` | Show Session, model and generation status |
 | `/qqping` | Check QQChat connectivity |
@@ -188,11 +193,15 @@ QQ Chat stores:
 
 Reflection runs asynchronously after the chat is idle or enough messages have accumulated. The **QQ Memory** action at the top of a QQ Session shows group and member memory. Memory snapshots refresh when a Session starts, the memory context expires, or the Session is compacted; continuous conversation does not repeatedly write the full memory. Enabled memory may reduce context-cache hit rate or increase input tokens, and can be disabled under **Settings -> QQ Chat -> Memory system** without deleting stored data.
 
-## Tool permissions
+## Permission management
+
+The settings page keeps media/file permissions separate from regular Agent-tool permissions:
 
-When **Group members can use tools** is enabled, group-triggered Agent turns may use the tools exposed by the current preset. When disabled, only the configured Owner stable ID may execute tools; other group members can still chat normally.
+- **Receive group-member media/files** controls whether images, files, audio and video are downloaded, stored and shown in the Session.
+- **Allow group members to read media/files** controls whether a group member's Agent turn may call QQChat media tools for the current attachment.
+- **Group members can use tools** controls whether group members may use regular Agent tools exposed by the current preset.
 
-Owner matching uses a stable QQ user ID, not a nickname.
+When regular tools or media reading are disabled, group members can still send normal text and receive replies. Owner matching uses a stable QQ user ID, not a nickname.
 
 ## Message display
 
@@ -204,6 +213,10 @@ QQ conversations use DSH's default Conversation UI:
 - QQ `@` mentions are converted to usernames when available.
 - The DSH Session composer can proactively send messages to QQ.
 
+## Session presets
+
+QQ Sessions use DSH's native Agent Preset mechanism. The preset configured for the plugin is only the default for new QQ Sessions. When a preset is selected for a blank Session in DSH Web, the selection is persisted with that Session and takes priority when the Session is resumed after a restart. You can also send `/qqpreset <preset>` as the first QQ message for that Session. Once a conversation has started, DSH locks the preset; use `/qqnew` to start another Session. The plugin does not copy DSH presets, tools or the AgentLoop.
+
 ## Notes
 
 - An official QQ Bot is required; personal QQ account login is not supported.
@@ -220,15 +233,12 @@ QR authorization and connection
 Group receive mode
 Group and direct-chat reply formats
 Memory system [on/off]
-Media and file permissions and regular tool permissions are independent settings:
-
-- **Receive group-member media/files** controls whether images, files, audio, and video are downloaded, stored, and shown in the session.
-- **Allow group members to read media/files** controls whether their Agent turns may call QQChat media tools for the current attachment.
-- **Group members can use tools** controls access to regular Agent tools.
 Owner stable ID
 Diagnostics and logs
 ```
 
+Media/file permissions and regular tool permissions are independent settings. See [Permission management](#permission-management) for their behavior.
+
 The Settings page does not contain chat lists, transcripts or memory browsing. Those remain in the normal DSH Session and Conversation surfaces.
 
 ## Persistence and memory scopes
@@ -247,7 +257,7 @@ Memory scopes are isolated as follows:
 - **Member:** typed profile, pattern, summary, daily and long-term memory for one stable sender.
 - **Direct chat:** uses the member scope for that QQ user.
 
-The same stable sender may retain member memory across groups under the same Bot. Group relationships and group-specific facts never cross group scopes. Reflection runs after roughly 120 seconds of inactivity or 20 unreflected messages, and can also compress older daily records after the configured thresholds.
+The same stable sender may retain user memory across groups under the same Bot. Group relationships and group-specific facts never cross group scopes, and different Bots keep separate user-memory scopes. Reflection runs after roughly 120 seconds of inactivity or 20 unreflected messages, and can also compress older daily records after the configured thresholds.
 
 ## Development
 

package/README.md

@@ -6,7 +6,8 @@
 
 <p>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
-  <img src="https://img.shields.io/badge/DSH-Plugin-6f42c1.svg" alt="DSH Plugin">
+  <img src="https://img.shields.io/badge/DSH-0.1.1--rc.2-6f42c1.svg" alt="DSH 0.1.1-rc.2">
+  <img src="https://img.shields.io/badge/QQChat-0.2.3-2ea44f.svg" alt="QQChat 0.2.3">
   <img src="https://img.shields.io/badge/TypeScript-5.x-3178c6.svg" alt="TypeScript">
 </p>
 
@@ -18,6 +19,8 @@
 
 <p><em>dsh-qqchat 是 DeepSeek Harness（DSH）的 QQ Bot 插件，支持 QQ 群聊、私聊、会话隔离、记忆系统和 DSH 原生命令。</em></p>
 
+<p>当前版本基于 DSH <code>0.1.1-rc.2</code> 验证，安装插件即可使用，无需修改或重新构建 DSH。</p>
+
 > 本项目是一个 Vibe Coding 项目，代码质量和工程完整性可能需要改进。如果你发现问题或有更好的实现建议，欢迎提交 [Issue](https://github.com/Coffeiz/dsh-qqchat/issues) 或 [Pull Request](https://github.com/Coffeiz/dsh-qqchat/pulls)。
 
 </div>
@@ -35,12 +38,13 @@
 | 私聊流式回复 | 私聊可选用 QQ 官方流式消息接口逐步更新回复 | 仅适用于私聊；纯文本兼容模式自动关闭；部分客户端可能不可见 |
 | 消息引用与 @ | 支持引用消息和 QQ @消息 | @用户优先显示用户名 |
 | 会话隔离 | QQ 群聊和私聊分别使用独立会话 | 不同群、不同用户的上下文互相隔离 |
-| 记忆系统 | 保存群聊、群成员和私聊用户的独立记忆 | 设置中可关闭；关闭不会删除已有记忆 |
+| 记忆系统 | 保存群聊、群成员和私聊用户的独立记忆；同一 Bot 下的用户记忆支持跨群复用 | 群关系和群级事件不会跨群共享；设置中可关闭 |
 | 记忆整理 | 自动将近期记录整理为长期记忆 | 后台执行，不阻塞正常回复 |
 | 媒体与文件权限 | 分别控制群成员媒体接收、媒体读取和普通工具使用 | Owner 与私聊默认不受限制 |
-| 工具权限 | 单独控制群成员是否可以使用普通 Agent 工具 | 可指定 Owner，按稳定用户 ID 判断 |
+| 权限管理 | 单独控制群成员是否可以使用普通 Agent 工具、读取媒体和接收文件 | 可指定 Owner，按稳定用户 ID 判断 |
 | DSH / QQChat 命令 | QQ 中直接执行 `/compact`、`/goal`、`/plan`、`/qqmodel`、`/qqstatus` 等命令 | 命令不经过模型；发送 `/qqhelp` 查看完整列表 |
 | DSH 原生界面 | 使用 DSH 默认会话、聊天区和输入框 | 支持从 DSH 主动向 QQ 发送消息 |
+| Session Preset | 每个 QQ Session 可使用 DSH 原生 preset | 新 Session 使用插件默认 preset；Session 自己选择后独立保存 |
 | 日志查看 | 在设置页查看 QQ Chat 运行日志 | 方便排查连接和消息问题 |
 
 ## 如何使用
@@ -67,7 +71,7 @@
     <td width="50%" valign="top">
       <img src="./docs/assets/记忆系统.jpg" width="100%" alt="QQ Chat 群聊记忆系统">
       <h3>记忆系统</h3>
-      <p>插件会分别维护群聊、群成员和私聊用户的记忆。成员记忆支持资料、群内称呼、历史昵称、行为模式和长期信息；近期消息会在空闲或达到阈值后自动整理。记忆会作为 Session 上下文按需刷新，设置中可以关闭，关闭后不会删除已有数据。</p>
+      <p>插件会分别维护群聊、群成员和私聊用户的记忆。同一 Bot 下，基于稳定用户 ID 的用户记忆可以跨群复用；群内关系和群级事件只保留在对应群。成员记忆支持资料、群内称呼、历史昵称、行为模式和长期信息；近期消息会在空闲或达到阈值后自动整理。记忆会作为 Session 上下文按需刷新，设置中可以关闭，关闭后不会删除已有数据。</p>
     </td>
   </tr>
 </table>
@@ -100,7 +104,7 @@ npx @deepseek-ai/dsh --profile qqchat
 1. 启动 DSH Web。
 2. 打开 **设置 → QQ Chat**。
 3. 点击 **扫码连接**。
-4. 使用手机 QQ 扫描二维码，并选择要授权的官方 Bot。
+4. 使用手机 QQ 扫描二维码，并选择要授权的官方 Bot或手动填写 AppID 和 AppSecret 接入。
 5. 授权完成后，QQ Gateway 会自动连接。
 
 如果无法扫码，也可以选择 **手动配置**，填写 QQ 开放平台的 AppID 和 AppSecret，并按需选择沙箱环境。插件会先验证凭据，验证成功后再保存并启动 Gateway。
@@ -121,7 +125,7 @@ npx @deepseek-ai/dsh --profile qqchat
 
 ## 命令
 
-QQ 中以 `/` 开头的消息会交给命令系统处理，不会作为普通消息发送给模型。DSH 原生命令保持原名；QQChat 自有命令使用 `qq` 前缀。群聊中可以发送 `@Bot /help` 或 `@Bot /qqhelp`。
+QQ 中以 `/` 开头的消息会交给命令系统处理，不会作为普通消息发送给模型。DSH 原生命令保持原名；QQChat 自有命令使用 `qq` 前缀。群聊中可以发送 `@Bot /qqhelp`。
 
 | 命令 | 用途 |
 | --- | --- |
@@ -129,6 +133,7 @@ QQ 中以 `/` 开头的消息会交给命令系统处理，不会作为普通消
 | `/qqnew`、`/qqreset`、`/qqclear` | 保留旧 Session，下一条消息开始新的 QQ Session |
 | `/compact` | 手动压缩较早的会话历史 |
 | `/qqmodel [provider/]model` | 查看或切换当前群聊/私聊的模型 |
+| `/qqpreset [preset]` | 查看或切换当前空白 Session 的 Agent Preset；对话开始后需新建 Session |
 | `/qqstop` | 中止当前生成 |
 | `/qqstatus` | 查看当前 Session、模型和生成状态 |
 | `/qqping` | 测试 QQChat 连通性 |
@@ -162,11 +167,13 @@ QQ Chat 会分别保存：
 - 群成员记忆：成员的资料、群内称呼、历史昵称、行为特点和长期信息
 - 私聊记忆：与某个 QQ 用户的长期对话信息
 
+同一 Bot 下，用户记忆按照稳定用户 ID 跨群连续；群内关系、群级事件和群聊记录不会跨群混入。不同 Bot 的用户记忆相互隔离。
+
 记忆会在聊天空闲或积累到一定数量后异步整理，不会阻塞正常回复。可以从 QQ Session 顶部的 **QQ 记忆** 入口查看群和成员记忆。记忆内容会按需进入 Agent 上下文，启用后可能降低上下文缓存命中率并增加输入 token；可在 **设置 → QQ Chat → 记忆系统** 中关闭。
 
 记忆快照会在新 Session、记忆上下文过期或 Session 压缩后刷新，连续对话不会重复写入完整记忆。群级记忆和当前群员记忆分别管理，群持续活跃不会替潜水成员刷新成员记忆。
 
-## 工具权限
+## 权限管理
 
 在设置中，媒体与文件权限和普通工具权限分别控制：
 
@@ -188,6 +195,10 @@ QQ 对话会使用 DSH 的默认聊天界面显示：
 - 支持 QQ @消息转换为用户名
 - 支持从 DSH 会话输入框主动发送 QQ 消息
 
+## Session Preset
+
+QQ Session 使用 DSH 原生的 Agent Preset 机制。插件配置中的 preset 只作为新建 QQ Session 的默认值；在 DSH Web 中为某个空白 Session 选择 preset 后，选择结果会随该 Session 保存，重启或恢复后仍优先使用该 Session 最近一次选择。也可以在该 Session 的第一条 QQ 消息中发送 `/qqpreset <preset>` 完成选择。对话开始后 DSH 不允许更换 preset，此时请先使用 `/qqnew`。插件不复制 DSH 的 preset、工具或 AgentLoop。
+
 ## 注意事项
 
 - 需要 QQ 官方 Bot，不支持个人 QQ 账号登录。

package/client-src/settings.cts

@@ -201,7 +201,7 @@ export function QQSettings({ rpc }: { rpc: Rpc }) {
     h('div', { className: 'qqSetting' },
       h('div', null,
         h('div', { className: 'qqSettingTitle' }, '启用记忆系统'),
-        h('div', { className: 'qqSettingHelp' }, '记忆会注入每轮 Agent 上下文，并在空闲时整理近期消息；这可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')),
+        h('div', { className: 'qqSettingHelp' }, '记忆会在新 Session、上下文 TTL 过期、记忆变化或 Session 压缩后刷新，不会每轮重复注入完整上下文；后台会在空闲时整理近期消息。启用记忆可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')),
       h('div', { className: 'qqControl' }, h(Button, { size: 'sm', variant: settings.memoryEnabled ? 'primary' : 'outline', onClick: () => void patch({ memoryEnabled: !settings.memoryEnabled }) }, settings.memoryEnabled ? '已启用' : '已关闭'))))
   const ownerSetting = !settings.groupMembersCanUseTools
     ? h('div', { className: 'qqSetting' },

package/docs/ARCHITECTURE.en.md

@@ -47,7 +47,9 @@ QQ Direct · <nickname>
 
 The Client no longer registers a `sidebar.footer.action` chat picker. QQ Sessions are listed and opened by DSH's normal Session/Workspace Browser.
 
-A new silent-only peer would otherwise remain blank because DSH uses `turn/start` to decide whether a Session has begun. The plugin submits one internal `qq-chat-bootstrap` wake and rejects it in `agent/pre-step`. This leaves a durable turn boundary while producing no model step, no LLM call, no QQ output and no model-visible bootstrap content.
+QQChat no longer submits an internal bootstrap wake. A newly created silent Session remains blank according to DSH's own semantics, so the native DSH Agent Preset selector can be used before the first Agent turn. The first QQ message that actually wakes the Agent creates the normal turn boundary.
+
+The plugin's `agentPreset` setting applies only to new Sessions. When a preset is selected in DSH Web, DSH records an `agent-preset/selected` event. QQChat reads that event when resuming the Session and restores the Session's most recent preset selection.
 
 ## Settings boundary
 
@@ -56,8 +58,9 @@ A new silent-only peer would otherwise remain blank because DSH uses `turn/start
 ```text
 QR authorization / connection
 Auto reply / Mention only / Silent record
-reply compatibility format
+group and direct-chat reply formats
 memory system [on/off]
+group-member media receive/read permissions
 group-member tool permission
 Owner stable ID
 plugin logs

package/docs/ARCHITECTURE.md

@@ -47,14 +47,9 @@ QQ私聊 · <昵称>
 
 Client 不再注册 `sidebar.footer.action` 会话选择器。QQ Session 直接由 DSH 自己的 Session/Workspace Browser 展示和打开。
 
-DSH 用 `turn/start` 判断一个 Session 是否仍为 blank。只有静默记录的新 QQ peer 没有正常 Agent turn，因此插件创建 Session 后提交一次 `qq-chat-bootstrap` wake，并在 `agent/pre-step` 立即 reject。结果是：
+QQChat 不再提交内部 bootstrap wake。新建的静默 Session 保持 DSH 原生 blank 状态，因此可以直接使用 DSH 的 Agent Preset 选择器；第一条真正触发 Agent 的 QQ 消息才会创建正常 turn boundary。
 
-- 有 durable turn boundary；
-- Session 能进入 DSH 正常列表；
-- 没有 model step；
-- 不调用 LLM；
-- 不发送 QQ 消息；
-- bootstrap 不进入模型 history。
+插件配置中的 `agentPreset` 只用于新 Session。Session 被 DSH Web 选择过 preset 后，DSH 会写入 `agent-preset/selected` 事件；QQChat 恢复 Session 时读取该事件，优先恢复 Session 最近一次选择的 preset。
 
 ## Settings 边界
 
@@ -132,6 +127,11 @@ session.append('qqchat/message', ...)
 - 不会唤醒 Agent；
 - 不会调用 LLM。
 
+官方 DSH 当前不会为 out-of-tree 插件事件提供正式注册 API。QQChat 在插件加载时
+按兼容约定把 `qqchat/message` 注册到可达的 DSH `KNOWN_SESSION_EVENT_TYPES` 副本，
+因此正常安装后旧 Session 可以继续恢复；如果某个特殊打包环境无法解析到宿主使用的
+事件表，QQChat 会捕获恢复失败并创建新的 QQ Session，完整 QQ 历史仍保存在 SQLite。
+
 插件不再从 SQLite 重放整段历史到 DSH Session。DSH Session 保存它实际经历过的 display/Agent events，完整 QQ 世界历史始终由 SQLite 负责。
 
 ## Host / Client

package/docs/DEVELOPMENT.md

@@ -10,7 +10,32 @@ QQChat 是 TypeScript 插件，Host 和 Client 一起构建。日常开发不需
 - 可用的 DSH workspace
 - 需要真实网关验证时，准备 QQ 官方 Bot 凭据；凭据只放在本地 Host 配置中
 
-仓库当前不提交 `package-lock.json`，使用 `npm install` 安装依赖。
+仓库提交 `package-lock.json`，使用 `npm install` 安装依赖并保持发布安装结果一致。
+
+## DSH 兼容要求
+
+插件以官方发布版 DSH 为运行基线。安装者不需要修改 DSH 源码、锁文件或构建流程；插件自身也不能依赖本地 DSH patch 或未发布的私有接口。
+
+验证插件兼容性时，应在干净的官方 DSH 工作区中检查：
+
+1. DSH 本地工作区没有插件补丁或未提交修改。
+2. 插件依赖的 DSH 包版本与官方发布版本一致。
+3. 插件 `npm run check` 能独立通过。
+4. 启动 DSH Web 后，插件 Host、Client 和设置页都能正常加载。
+
+当前已知的宿主兼容边界见[架构说明](./ARCHITECTURE.md)和[媒体与引用方案](./MEDIA_AND_QUOTES.md)：自定义 `qqchat/message` 展示事件不属于官方 DSH 的标准 Agent 事件，插件会在加载时自动注册事件类型；若特殊打包环境无法找到宿主事件表，才会触发新建 Session 的降级，QQ 完整历史仍由自身 SQLite 保存。该兼容层不要求用户修改 DSH。
+
+## 当前功能兼容矩阵
+
+| 功能 | DSH 原生支持情况 | 插件行为 |
+| --- | --- | --- |
+| QQ 文本消息与独立 Session | 无 QQ 协议支持 | 转换为 DSH 标准 user message，并保留 QQ 身份元数据 |
+| 群友静默记录、未 @ 消息展示 | 无 QQ 自定义展示事件 | 使用插件 Client 渲染 `qqchat/message`；不送入模型 |
+| 图片输入 | 取决于当前 DSH 模型路由和附件服务 | 使用 DSH 原生图片块；不支持视觉时使用稳定文本降级和读取工具 |
+| 音频、视频和普通文件 | DSH 不提供统一的 QQ 媒体理解能力 | 保存附件并提供类型提示、文件工具或媒体信息工具 |
+| QQ 私聊流式回复 | DSH 不负责 QQ Gateway 流式协议 | 插件调用 QQ 官方接口；失败时回退普通发送，纯文本兼容模式自动关闭 |
+| QQ 引用、@和气泡 | DSH 不认识 QQ 协议字段 | 插件把引用和 @ 转为可读文本/元数据，并由 Client 做展示 |
+| DSH 原生命令 | DSH 只处理 DSH Web 自己收到的命令 | 插件将 `/qq...` 命令解析后转交或执行，避免与 DSH 原命令冲突 |
 
 ## 本地安装与检查
 

package/docs/MEDIA_AND_QUOTES.md

@@ -14,7 +14,7 @@
 
 本文是设计与审查文档，不代表所有功能已经实现。
 
-当前实现进度：Phase 0–2 的基础链路已完成，Phase 3–4 已完成媒体接收、元数据工具、引用关系和附件复用的 Host 侧基础能力。已包含标准化媒体/引用类型、QQ 附件解析、SQLite 附件关系、安全下载、媒体清理、图片附件接入、`qqchat_describe_image`、`qqchat_read_file`、`qqchat_media_info` 和 JSON 可序列化的 Web transcript 摘要。DSH Web 中针对自定义 transcript 的原生媒体 renderer、文件/音频/视频播放能力、短 TTL 媒体 URL 和真实环境验收仍未完成，不能视为完整的 Phase 3–4 交付。
+当前实现进度：Phase 0–2 已完成，Phase 3–4 的 Host 侧基础能力已完成，包括媒体接收、元数据工具、引用关系、引用索引和附件复用。已包含标准化媒体/引用类型、QQ 附件解析、SQLite 附件关系、安全下载、媒体清理、图片附件接入、`qqchat_describe_image`、`qqchat_read_file`、`qqchat_media_info` 和 JSON 可序列化的 Web transcript 摘要。Agent 触发消息已经使用 DSH 原生图片块；静默 transcript 的图片目前通过受保护的 RPC data URL 做最小适配。DSH Web 自定义 transcript 的完整原生媒体 renderer、文件/音频/视频播放器、短 TTL 媒体 URL 和真实环境验收仍未完成，因此不能视为完整的 Web 侧 Phase 3–4 交付。
 
 Web 渲染后续采用“DSH 原生优先”的方案：触发 Agent 的消息使用 DSH 原生消息内容和 `ImageBlock`；静默记录或未触发 Agent 的 QQ transcript 只增加最小的附件适配，不另建一套气泡、图片预览、文件卡片或媒体主题。这样不会为了显示媒体而改变群聊接收模式或额外唤醒 Agent。
 
@@ -280,20 +280,21 @@ QQ dispatch
 
 ## 模型输入策略
 
-### 第一阶段：官方兼容模式
+### 兼容与降级路径
 
-默认采用官方 `dsh-qqbot` 的思路：
+当前以 DSH 原生图片输入为主，无法使用原生视觉输入时由 DSH 统一降级：
 
 - 图片、视频、文件先保存为附件；
-- Agent 文本上下文注入媒体类型、名称和附件 ID/受控本地路径；
-- 图片通过 `qqchat_describe_image` 或等价工具分析；
+- Agent 文本上下文保留媒体类型、名称和附件 ID；
+- 图片优先作为 DSH `ImageBlock` 输入；纯文本模型收到 DSH 生成的稳定图片占位文本；
+- `qqchat_describe_image` 仅用于模型主动按 attachment ID 重新读取图片；
 - 视频交给 `ffmpeg` 和文件工具；
 - 文本文件可以直接读取内容；
 - 无能力处理的媒体只提供结构化提示。
 
-优点是对模型要求低，不会改变所有 QQ turn 的模型路由，也不会把大量二进制内容直接塞进上下文缓存。
+优点是沿用 DSH 的统一模型能力判断、图片预算和附件处理，不需要插件复制一套模型适配逻辑。
 
-### 第二阶段：图片原生输入
+### 图片原生输入
 
 当当前模型明确声明支持 image modality 时，可以将图片附件转换为 DSH 官方 `ImageAttachmentRef`，构造 `ImageBlock` 发送给视觉模型。
 
@@ -395,7 +396,7 @@ createUserMessage({
 })
 ```
 
-这样图片由 DSH Web 原生消息渲染，同时可以进入视觉模型。文本模型或附件服务不可用时，必须退回当前的文本提示和 `qqchat_describe_image` 工具路径，不能让整轮消息失败。
+这样图片由 DSH Web 原生消息渲染，同时可以进入视觉模型。文本模型会由 DSH 统一投影为稳定的图片占位文本；`qqchat_describe_image` 仅作为按 attachment_id 主动重新读取图片的工具，不是正常视觉输入的必经路径。
 
 #### 静默消息：最小适配的附件读取 RPC
 
@@ -467,9 +468,9 @@ createUserMessage({
 网页显示必须复用 DSH 原生消息和附件样式：
 
 - 图片显示缩略图和可选的打开动作；
-- 语音显示播放条；
-- 视频显示文件卡片或预览入口；
-- 文件显示名称、大小和下载/保存入口；
+- 语音、视频和文件目前保存并展示受限的元数据摘要；
+- Agent 侧可通过媒体工具读取允许范围内的文件或媒体；
+- Web 侧完整播放器、下载/保存动作仍等待 DSH 公开 renderer 接口；
 - 引用消息显示独立的引用块，正文和引用附件分开；
 - 不在插件里重新实现 DSH 的气泡、输入框、Modal、图片预览、文件卡片或附件基础样式；
 - 插件 Client 只负责把 QQ 消息、引用和附件转换成 DSH renderer 能消费的结构。
@@ -479,9 +480,9 @@ createUserMessage({
 ### A. DSH 原生能力确认
 
 - [x] 确认当前 DSH 核心对 `ImageBlock`、`ImageAttachmentRef` 和附件引用的输入边界；
-- [ ] DSH 当前未向插件公开完整的图片预览、放大、加载失败和空状态组件接口，QQChat 不复制这些基础组件；（待与实际 Web renderer 接口确认）
-- [ ] 确认 DSH 原生文件、音频、视频展示组件是否可以由插件复用；
-- [ ] 确认自定义 `qqchat/message` event 是否能直接承载 DSH 原生附件引用；
+- [x] 确认 DSH 当前对图片块和附件引用的输入边界；
+- [x] 确认 DSH 尚未向插件公开可直接复用的自定义 transcript 图片、文件、音频、视频 renderer 接口；
+- [x] 确认自定义 `qqchat/message` event 不能直接承载 DSH 原生附件块；
 - [x] 自定义 event 不能直接变成原生 `ImageBlock` 时，记录并采用最小适配边界，不复制 DSH 基础组件。
 
 ### B. Host 附件读取和权限
@@ -491,7 +492,7 @@ createUserMessage({
 - [x] 校验附件是否已经关联到当前消息、引用消息和会话范围；
 - [x] 校验附件状态、过期时间和图片读取大小；媒体类型由入站媒体归一化和 DSH 图片附件服务共同校验；
 - [x] 图片响应优先带回 DSH 原生 `ImageAttachmentRef`；仅为当前自定义 transcript 的图片预览提供受限 data URL；
-- [ ] 当前实现尚未使用短 TTL URL，而是使用受大小限制的 RPC 响应 data URL；后续接入 DSH renderer 后应移除该 fallback；
+- [x] 当前实现使用受大小限制的 RPC 响应 data URL；接入 DSH renderer 后应替换为短 TTL 的受保护引用；
 - [x] 不把 QQ 原始签名 URL、AppSecret、Token 或本地文件路径返回给 Client；
 - [x] 无权限、过期、删除和超限附件会被拒绝；损坏文件由 RPC 失败处理，不泄露存储路径。
 
@@ -500,7 +501,7 @@ createUserMessage({
 - [x] 当前模型支持图片时，将 QQ 图片保存为 DSH `ImageAttachmentRef`；
 - [x] 在同一条 DSH `user/message` 中加入文本块和 `ImageBlock`；
 - [x] 让 DSH Web 原生显示 Agent 图片，同时让视觉模型直接接收图片；
-- [x] 当前模型不支持图片时，退回 `qqchat_describe_image` 工具；
+- [x] 当前模型不支持图片时，由 DSH 统一投影为稳定图片占位文本；主动重新读取图片仍可使用 `qqchat_describe_image`；
 - [x] 附件服务不可用、图片损坏或图片超限时，保留文本提示/工具 fallback，不让整轮媒体失败；
 - [x] 保证所有 `ImageBlock` 在 Session event 发布前已经持久提交；
 - [x] 保证 Session event 中不存在 Buffer、Blob、本地路径、SDK 原始对象或循环引用。
@@ -509,11 +510,10 @@ createUserMessage({
 
 - [x] 静默消息继续使用 `qqchat/message`，不为了显示媒体改成 `user/message`；
 - [x] event 只携带 JSON 可序列化的附件摘要：ID、类型、文件名、大小、引用标记；
-- [ ] 优先寻找 DSH 原生 renderer 消费自定义 event 附件的方式；
-- [ ] 当前没有自定义 event 的原生入口，尚未完成无主题的薄适配层；
-- [ ] 薄适配层只负责附件引用转换和加载状态，不复制气泡、Modal、按钮或预览组件；
+- [x] 已确认当前没有自定义 event 的原生附件入口；
+- [x] 薄适配层只负责附件摘要、受保护读取和加载状态，不复制气泡、Modal、按钮或预览组件；
 - [x] 图片加载通过受保护的附件读取 RPC，保持与 DSH 原生附件引用相同的权限边界；
-- [ ] 文件、语音、视频先使用统一的 DSH 风格媒体卡片承载元数据；原生播放器待 DSH 暴露公开入口后接入；（当前只有 Host 元数据，不代表已有 Client 媒体卡片）
+- [x] 文件、语音、视频在当前 transcript 中只保留统一 JSON 元数据摘要；原生播放器待 DSH 暴露公开入口后接入；
 - [x] 加载失败、过期和无权限状态不显示原始 URL 或路径。
 
 ### E. 引用消息显示

package/docs/STREAMING.md

@@ -296,25 +296,28 @@ if (writer.sentFrameCount === 0) {
 }
 ```
 
-## 咕咕复用清单
-
-迁移时建议按以下顺序实现：
-
-- [ ] 确认 QQ SDK 的 `stream_messages` 请求和响应字段；
-- [ ] 仅为 C2C 私聊创建流式 Writer；
-- [ ] 从 DSH assistant text-delta 累计全文；
-- [ ] 使用 `replace`，不要直接把 delta 当作独立消息；
-- [ ] 为每个流生成新的 `msg_seq`；
-- [ ] `index` 从 0 开始严格递增；
-- [ ] 首帧响应后再读取和保存 `stream_msg_id`；
-- [ ] 所有请求通过串行队列；
-- [ ] 采用 300–500ms throttle；
-- [ ] 处理 429/50002 重试；
-- [ ] 失败时区分“未发送”和“已发送部分”；
-- [ ] 增加流式开关和普通发送回退；
-- [ ] 增加模拟 HTTP 测试：首帧、后续帧、结束帧、队列竞态、失败降级；
-- [ ] 真实 QQ 手机端和桌面端分别验证可见性；
-- [ ] 记录 `msg_seq`、`index`、是否有 `stream_msg_id`，但不要记录完整敏感正文。
+## 当前实现核对清单
+
+以下是当前 `dsh-qqchat` 对官方方案的落地情况：
+
+- [x] 使用 QQ 官方 `stream_messages` 请求和响应字段；
+- [x] 仅为 C2C 私聊创建流式 Writer；
+- [x] 从 DSH assistant text-delta 累计全文；
+- [x] 使用 `replace`，不把 delta 当作独立消息；
+- [x] 为每个流生成新的 `msg_seq`；
+- [x] `index` 从 0 开始严格递增；
+- [x] 首帧响应后再读取和保存 `stream_msg_id`；
+- [x] 所有请求通过串行队列；
+- [x] 使用节流减少更新频率；
+- [x] 对发送失败区分“尚未发送”和“已经发送部分”；
+- [x] 提供流式开关和普通发送回退；
+- [x] 使用模拟 HTTP 测试覆盖首帧、后续帧、结束帧和队列竞态；
+- [ ] 真实 QQ 手机端和桌面端分别验证所有客户端的可见性；
+- [x] 日志只记录 `msg_seq`、`index`、是否有 `stream_msg_id` 等定位信息，不记录完整敏感正文。
+
+### 已知故障：QQ `40054005` 去重
+
+QQ 会在 `msg_seq` 重复或流式上下文不完整时返回 `40054005`。当前实现为每个流生成新的序列号，并在首帧成功后把返回的 `stream_msg_id` 传给后续帧；如果流式首帧尚未成功，运行时会回退到普通发送，避免用户收不到回复。如果已经成功显示过部分流式内容，插件不会再发送一条完整重复消息，而是记录失败并结束本轮。
 
 ## 测试矩阵
 

package/lib/client.js

@@ -227,7 +227,7 @@ function QQSettings({ rpc }) {
         : settings.directStreamingEnabled
             ? '使用 QQ 官方流式接口逐步更新私聊回复；部分 QQ 客户端可能看不到流式效果。'
             : '使用普通一次性消息发送，兼容性更好。')))));
-    const memoryGroup = (0, shared_cjs_1.h)('div', { className: 'qqSettingsGroup' }, (0, shared_cjs_1.h)('h3', null, '记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSetting' }, (0, shared_cjs_1.h)('div', null, (0, shared_cjs_1.h)('div', { className: 'qqSettingTitle' }, '启用记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSettingHelp' }, '记忆会注入每轮 Agent 上下文，并在空闲时整理近期消息；这可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')), (0, shared_cjs_1.h)('div', { className: 'qqControl' }, (0, shared_cjs_1.h)(shared_cjs_1.Button, { size: 'sm', variant: settings.memoryEnabled ? 'primary' : 'outline', onClick: () => void patch({ memoryEnabled: !settings.memoryEnabled }) }, settings.memoryEnabled ? '已启用' : '已关闭'))));
+    const memoryGroup = (0, shared_cjs_1.h)('div', { className: 'qqSettingsGroup' }, (0, shared_cjs_1.h)('h3', null, '记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSetting' }, (0, shared_cjs_1.h)('div', null, (0, shared_cjs_1.h)('div', { className: 'qqSettingTitle' }, '启用记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSettingHelp' }, '记忆会在新 Session、上下文 TTL 过期、记忆变化或 Session 压缩后刷新，不会每轮重复注入完整上下文；后台会在空闲时整理近期消息。启用记忆可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')), (0, shared_cjs_1.h)('div', { className: 'qqControl' }, (0, shared_cjs_1.h)(shared_cjs_1.Button, { size: 'sm', variant: settings.memoryEnabled ? 'primary' : 'outline', onClick: () => void patch({ memoryEnabled: !settings.memoryEnabled }) }, settings.memoryEnabled ? '已启用' : '已关闭'))));
     const ownerSetting = !settings.groupMembersCanUseTools
         ? (0, shared_cjs_1.h)('div', { className: 'qqSetting' }, (0, shared_cjs_1.h)('div', null, (0, shared_cjs_1.h)('div', { className: 'qqSettingTitle' }, 'Owner stable ID'), (0, shared_cjs_1.h)('div', { className: 'qqSettingHelp' }, '使用 stable sender ID，不根据昵称判断。')), (0, shared_cjs_1.h)('div', { className: 'qqControl' }, (0, shared_cjs_1.h)(shared_cjs_1.Input, {
             value: settings.ownerUserId,

package/lib/gateway/api.d.ts

@@ -14,7 +14,7 @@ export declare class QQApiClient {
     constructor(db: QQChatDatabase, config: QQChatConfig);
     clearToken(accountId: number): void;
     token(account: AccountRow): Promise<string>;
-    gatewayUrl(account: AccountRow): Promise<string>;
+    gatewayUrl(account: AccountRow, retry?: boolean): Promise<string>;
     private nextSeq;
     /**
      * QQ stream_messages requires a fresh msg_seq for each stream session.

package/lib/gateway/api.js

@@ -32,12 +32,16 @@ export class QQApiClient {
         this.tokens.set(id, { token: data.access_token, expiresAt: Date.now() + Math.max(60, ttl) * 1000 });
         return data.access_token;
     }
-    async gatewayUrl(account) {
+    async gatewayUrl(account, retry = true) {
         const token = await this.token(account);
         const base = account.sandbox ? SANDBOX_API_BASE : API_BASE;
         const response = await fetch(`${base}/gateway`, {
             headers: { Authorization: `QQBot ${token}` }, signal: AbortSignal.timeout(15_000),
         });
+        if (response.status === 401 && retry) {
+            this.clearToken(account.id);
+            return this.gatewayUrl(account, false);
+        }
         const data = await safeJson(response);
         if (!response.ok || !data?.url)
             throw new Error(`QQ gateway 获取失败: HTTP ${response.status}`);

package/lib/gateway/gateway.js

@@ -72,7 +72,11 @@ export class QQGateway {
         }
     }
     async connectOnce() {
-        const [url, token] = await Promise.all([this.api.gatewayUrl(this.account), this.api.token(this.account)]);
+        // Resolve the URL first. gatewayUrl may invalidate and refresh a stale
+        // cached token after a 401; fetching the identify token in parallel could
+        // otherwise retain the pre-refresh token for the WebSocket handshake.
+        const url = await this.api.gatewayUrl(this.account);
+        const token = await this.api.token(this.account);
         await new Promise((resolve, reject) => {
             const ws = new WebSocket(url);
             this.ws = ws;

package/lib/index.js

@@ -10,6 +10,8 @@ import { QQApiClient } from './gateway/api.js';
 import { QQBindService } from './gateway/auth.js';
 import { createQQChatRpc } from './transport/rpc.js';
 import { QQChatRuntime } from './session/runtime.js';
+import { registerQQChatSessionEventType } from './session/registration.js';
+const qqChatSessionEventRegistrations = await registerQQChatSessionEventType();
 export const name = 'dsh-qqchat';
 export const inject = ['connection', 'agents', 'agentDefaultModel', 'commands', 'llm', 'tools', 'workspaceRegistry'];
 export function apply(ctx, inputConfig = {}) {
@@ -18,6 +20,9 @@ export function apply(ctx, inputConfig = {}) {
     const db = new QQChatDatabase(join(config.dataDir, 'qqchat.sqlite'));
     const baseLogger = ctx.logger || console;
     const logger = new QQChatLogger(baseLogger);
+    if (qqChatSessionEventRegistrations === 0) {
+        logger.warn?.('[dsh-qqchat] 未找到可注册的 DSH Session 事件表，旧 QQChat Session 恢复可能需要新建 Session');
+    }
     const api = new QQApiClient(db, config);
     const auth = new QQBindService(db, config);
     const memory = new MemoryEngine(ctx, db, config, logger);

package/lib/media/image-tool.d.ts

@@ -1,4 +1,4 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { QQChatDatabase } from '../storage/db.js';
-/** Exposes stored QQ images through DSH's durable image-block seam. */
+/** Exposes stored QQ images by attachment ID when a model explicitly requests one. */
 export declare function registerQQImageTool(ctx: Context, db: QQChatDatabase, isAllowed?: (agentId: string, attachmentId: string) => boolean): () => void;

package/lib/media/image-tool.js

@@ -1,9 +1,9 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
-/** Exposes stored QQ images through DSH's durable image-block seam. */
+/** Exposes stored QQ images by attachment ID when a model explicitly requests one. */
 export function registerQQImageTool(ctx, db, isAllowed = () => true) {
     const definition = defineTool({
         name: 'qqchat_describe_image',
-        description: '查看 QQ 消息中的图片。传入 QQChat 提供的 attachment_id，可用于 OCR、截图、界面和照片分析。',
+        description: '按 attachment_id 主动重新读取 QQ 消息中的图片。正常图片消息由 DSH 原生视觉输入链路直接处理；本工具用于模型需要再次读取指定图片的场景。',
         parameters: {
             attachment_id: { type: 'string', required: true, description: 'QQChat 图片附件 ID' },
         },

package/lib/session/agent-bridge.d.ts

@@ -1,8 +1,11 @@
 import type { Context } from '@deepseek-ai/cordis';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
 import '../shared/augmentations.js';
 import type { QQChatDatabase } from '../storage/db.js';
 import type { MemoryEngine } from '../storage/memory.js';
 import type { ChatType, GroupRow, LoggerLike, MemberRow, StoredAttachmentSummary, QQChatConfig, QQChatDisplayEvent, QQNormalizedMessage } from '../types.js';
+export declare function resolveQQSessionPreset(header: Session['header'], events: readonly SessionEvent[]): string | undefined;
 export declare class DshQQBridge {
     private readonly ctx;
     private readonly db;
@@ -21,7 +24,6 @@ export declare class DshQQBridge {
     private readonly memorySnapshots;
     private readonly disposeEvent;
     private readonly disposeToolGate;
-    private readonly disposeBootstrapGate;
     private readonly disposeCommands;
     private readonly disposeImageTool;
     private readonly disposeMediaTools;
@@ -36,13 +38,11 @@ export declare class DshQQBridge {
     private ensureAgent;
     private isArchived;
     private rememberRoute;
-    private ensureVisible;
     private appendDisplayIfMissing;
     private appendOwnerMessageIfMissing;
     private ensureTitle;
     private tryResume;
     private agentOptions;
-    private imageRouteAvailable;
     private ensureSelection;
     private selection;
     private requestReset;
@@ -50,7 +50,11 @@ export declare class DshQQBridge {
     private commandHelp;
     private registerCommands;
     private modelCommand;
+    private presetCommand;
     private statusCommand;
     private composition;
+    private persistedPreset;
     private serial;
 }
+/** Build the durable DSH content for one QQ turn without pre-flighting the model. */
+export declare function qqMessageContent(text: string, attachments: readonly StoredAttachmentSummary[]): ContentBlock[];