dsh-qqchat 0.2.2 → 0.2.4

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).
@@ -217,7 +220,7 @@ QQ Sessions use DSH's native Agent Preset mechanism. The preset configured for t
 ## Notes
 
 - An official QQ Bot is required; personal QQ account login is not supported.
-- `0.2.1` is still being refined; test with a dedicated Bot and group first.
+- `0.2.2` is still being refined; test with a dedicated Bot and group first.
 - Rich media, full QQ emoji handling and some complex message formats may require compatibility mode.
 - Uninstalling the plugin does not automatically delete saved chat or memory data.
 

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>
@@ -199,7 +202,7 @@ QQ Session 使用 DSH 原生的 Agent Preset 机制。插件配置中的 preset
 ## 注意事项
 
 - 需要 QQ 官方 Bot，不支持个人 QQ 账号登录。
-- `0.2.1` 仍在持续完善，建议先在测试 Bot 和测试群中使用。
+- `0.2.2` 仍在持续完善，建议先在测试 Bot 和测试群中使用。
 - 富媒体、完整 QQ 表情和部分复杂消息格式可能需要使用兼容模式。
 - 卸载插件不会自动删除已经保存的聊天和记忆数据。
 

package/client-src/plugin.cts

@@ -1,4 +1,4 @@
-import { installStyles, setQQRpc } from './shared.cjs'
+import { installQQSettingsIcon, installStyles, setQQRpc } from './shared.cjs'
 import type { Ctx } from './shared.cjs'
 import { QQSettings } from './settings.cjs'
 import { QQSessionUtility, QQTranscriptNode, createQQMessageDefinition } from './workspace.cjs'
@@ -7,6 +7,7 @@ exports.inject = ['slots', 'connection', 'conversationEvents'] as const
 exports.apply = function apply(ctx: Ctx) {
   setQQRpc(ctx.connection.rpc)
   ctx.effect(installStyles, 'dsh-qqchat: client styles')
+  ctx.effect(installQQSettingsIcon, 'dsh-qqchat: QQ settings icon')
   ctx.conversationEvents.register(createQQMessageDefinition())
 
   ctx.slots.inject('settings.section', () => ctx.slots.register({ name: 'settings.section', id: 'qqchat', order: 35, label: () => 'QQ Chat', inject: () => ({ rpc: ctx.connection.rpc }) }, QQSettings))

package/client-src/shared.cts

@@ -55,6 +55,47 @@ export interface SidebarActionProps { wide: boolean; rpc: Rpc; sessions: Session
 export const CHANNEL = '/qqchat'
 const STYLE_ID = 'dsh-qqchat/client-ui-v2'
 
+const QQ_ICON_PATH = 'M17.5359 12.5144L16.8402 10.7175C16.8408 10.6968 16.8494 10.3429 16.8494 10.1604C16.8494 7.08792 15.448 4.0003 12.0012 4C8.55459 4.0003 7.15292 7.08792 7.15292 10.1604C7.15292 10.3429 7.16151 10.6968 7.16209 10.7175L6.4667 12.5144C6.27608 13.0285 6.08776 13.564 5.94988 14.0232C5.29262 16.2126 5.50559 17.1186 5.66783 17.139C6.01581 17.1823 7.02221 15.4908 7.02221 15.4908C7.02221 16.4704 7.5095 17.7487 8.56405 18.6719C8.16963 18.7976 7.68635 18.9911 7.37564 19.2284C7.09645 19.442 7.13142 19.6594 7.18158 19.7473C7.40258 20.1329 10.9713 19.9935 12.0017 19.8733C13.0319 19.9935 16.6009 20.1329 16.8216 19.7473C16.872 19.6594 16.9067 19.442 16.6275 19.2284C16.3168 18.9911 15.8333 18.7976 15.4386 18.6716C16.4928 17.7487 16.9801 16.4704 16.9801 15.4908C16.9801 15.4908 17.9868 17.1823 18.3348 17.139C18.4967 17.1186 18.7131 16.2108 18.0524 14.0232C17.9125 13.56 17.7265 13.0285 17.5359 12.5144ZM18.5574 20.7407C18.1843 21.3926 17.7237 21.6334 17.1187 21.7981C16.8792 21.8633 16.621 21.9056 16.325 21.936C15.8844 21.9814 15.3392 22.001 14.712 22C13.786 21.9985 12.693 21.9491 12.0017 21.884C11.3103 21.9491 10.2173 21.9985 9.29129 22C8.66414 22.001 8.11889 21.9814 7.67832 21.936C7.38236 21.9056 7.12409 21.8633 6.88467 21.7981C6.27994 21.6335 5.81954 21.393 5.44496 20.7393C5.15165 20.2258 5.07747 19.6406 5.20612 19.0866C4.61376 18.9546 4.20483 18.6045 3.92733 18.1757C3.77911 17.9466 3.68408 17.7127 3.61845 17.4663C3.53001 17.1344 3.49486 16.7666 3.50184 16.3601C3.51532 15.5749 3.68902 14.5984 4.03435 13.4481C4.17427 12.9821 4.3614 12.4396 4.6015 11.7926L5.15467 10.3632C5.1536 10.287 5.15292 10.2154 5.15292 10.1604C5.15292 5.6047 7.58875 2.00038 12.0013 2C16.4138 2.00038 18.8494 5.60454 18.8494 10.1604C18.8494 10.2154 18.8487 10.2869 18.8477 10.3631L19.401 11.7923L19.4112 11.8191C19.636 12.4254 19.8242 12.9722 19.967 13.445C20.3145 14.5956 20.4889 15.5735 20.5018 16.361C20.5085 16.768 20.4728 17.1365 20.3837 17.4689C20.3178 17.7148 20.2228 17.9483 20.0746 18.1768C19.7976 18.6041 19.3905 18.9532 18.7974 19.0862C18.9266 19.6411 18.8523 20.2274 18.5574 20.7407Z'
+
+/** Temporarily replaces DSH's fallback settings glyph for the QQ Chat row. */
+export function installQQSettingsIcon(): () => void {
+  const originals = new Map<HTMLButtonElement, SVGElement>()
+  const apply = () => {
+    for (const button of Array.from(document.querySelectorAll('button'))) {
+      const label = button.querySelector('span[class$="_navLabel"]')
+      if (label?.textContent?.trim() !== 'QQ Chat') continue
+      if (button.querySelector('[data-dsh-qqchat-icon]')) continue
+      const icon = button.querySelector('svg[class$="_navIcon"]')
+      if (!icon) continue
+      originals.set(button, icon.cloneNode(true) as SVGElement)
+      icon.remove()
+      const replacement = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+      replacement.setAttribute('width', '16')
+      replacement.setAttribute('height', '16')
+      replacement.setAttribute('viewBox', '0 0 24 24')
+      replacement.setAttribute('fill', 'currentColor')
+      replacement.setAttribute('aria-hidden', 'true')
+      replacement.setAttribute('data-dsh-qqchat-icon', 'true')
+      replacement.classList.add('dsh-qqchat-nav-icon')
+      const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')
+      path.setAttribute('d', QQ_ICON_PATH)
+      replacement.append(path)
+      button.insertBefore(replacement, label)
+    }
+  }
+  const observer = new MutationObserver(apply)
+  observer.observe(document.body, { childList: true, subtree: true })
+  apply()
+  return () => {
+    observer.disconnect()
+    for (const [button, original] of originals) {
+      const replacement = button.querySelector('[data-dsh-qqchat-icon]')
+      if (replacement) replacement.replaceWith(original)
+    }
+    originals.clear()
+  }
+}
+
 const css = `
 .qqs{display:flex;flex-direction:column;gap:18px;color:var(--dsw-alias-label-primary);font:inherit}.qqs *{box-sizing:border-box}
 .qqsHead{display:flex;align-items:center;justify-content:space-between;gap:12px}.qqsBrand{display:flex;align-items:center;gap:10px}.qqsLogo{width:34px;height:34px;border-radius:10px;display:grid;place-items:center;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l1);font-weight:700}.qqsTitle{font-size:15px;font-weight:620}.qqMuted{font-size:12px;color:var(--dsw-alias-label-secondary);line-height:1.55}.qqStatus{display:flex;align-items:center;gap:7px;font-size:12px;color:var(--dsw-alias-label-secondary)}.qqDot{width:7px;height:7px;border-radius:50%;background:var(--dsw-alias-state-warn-primary)}.qqDot.online{background:var(--dsw-alias-state-success-primary)}

package/docs/ARCHITECTURE.md

@@ -127,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

@@ -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
 
@@ -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 原始对象或循环引用。

package/lib/client.js

@@ -10,6 +10,7 @@ exports.inject = ['slots', 'connection', 'conversationEvents'];
 exports.apply = function apply(ctx) {
     (0, shared_cjs_1.setQQRpc)(ctx.connection.rpc);
     ctx.effect(shared_cjs_1.installStyles, 'dsh-qqchat: client styles');
+    ctx.effect(shared_cjs_1.installQQSettingsIcon, 'dsh-qqchat: QQ settings icon');
     ctx.conversationEvents.register((0, workspace_cjs_1.createQQMessageDefinition)());
     ctx.slots.inject('settings.section', () => ctx.slots.register({ name: 'settings.section', id: 'qqchat', order: 35, label: () => 'QQ Chat', inject: () => ({ rpc: ctx.connection.rpc }) }, settings_cjs_1.QQSettings));
     ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({ name: 'conversation.chat.node', key: 'qqchat-message' }, workspace_cjs_1.QQTranscriptNode));
@@ -249,6 +250,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.dateTime = exports.time = exports.initials = exports.short = exports.CHANNEL = exports.h = exports.useSyncExternalStore = exports.useState = exports.useMemo = exports.useEffect = exports.useCallback = exports.Menu = exports.Input = exports.Button = exports.React = void 0;
 exports.setQQRpc = setQQRpc;
 exports.getQQRpc = getQQRpc;
+exports.installQQSettingsIcon = installQQSettingsIcon;
 exports.installStyles = installStyles;
 exports.call = call;
 exports.Modal = Modal;
@@ -265,6 +267,49 @@ function setQQRpc(rpc) { qqRpc = rpc; }
 function getQQRpc() { return qqRpc; }
 exports.CHANNEL = '/qqchat';
 const STYLE_ID = 'dsh-qqchat/client-ui-v2';
+const QQ_ICON_PATH = 'M17.5359 12.5144L16.8402 10.7175C16.8408 10.6968 16.8494 10.3429 16.8494 10.1604C16.8494 7.08792 15.448 4.0003 12.0012 4C8.55459 4.0003 7.15292 7.08792 7.15292 10.1604C7.15292 10.3429 7.16151 10.6968 7.16209 10.7175L6.4667 12.5144C6.27608 13.0285 6.08776 13.564 5.94988 14.0232C5.29262 16.2126 5.50559 17.1186 5.66783 17.139C6.01581 17.1823 7.02221 15.4908 7.02221 15.4908C7.02221 16.4704 7.5095 17.7487 8.56405 18.6719C8.16963 18.7976 7.68635 18.9911 7.37564 19.2284C7.09645 19.442 7.13142 19.6594 7.18158 19.7473C7.40258 20.1329 10.9713 19.9935 12.0017 19.8733C13.0319 19.9935 16.6009 20.1329 16.8216 19.7473C16.872 19.6594 16.9067 19.442 16.6275 19.2284C16.3168 18.9911 15.8333 18.7976 15.4386 18.6716C16.4928 17.7487 16.9801 16.4704 16.9801 15.4908C16.9801 15.4908 17.9868 17.1823 18.3348 17.139C18.4967 17.1186 18.7131 16.2108 18.0524 14.0232C17.9125 13.56 17.7265 13.0285 17.5359 12.5144ZM18.5574 20.7407C18.1843 21.3926 17.7237 21.6334 17.1187 21.7981C16.8792 21.8633 16.621 21.9056 16.325 21.936C15.8844 21.9814 15.3392 22.001 14.712 22C13.786 21.9985 12.693 21.9491 12.0017 21.884C11.3103 21.9491 10.2173 21.9985 9.29129 22C8.66414 22.001 8.11889 21.9814 7.67832 21.936C7.38236 21.9056 7.12409 21.8633 6.88467 21.7981C6.27994 21.6335 5.81954 21.393 5.44496 20.7393C5.15165 20.2258 5.07747 19.6406 5.20612 19.0866C4.61376 18.9546 4.20483 18.6045 3.92733 18.1757C3.77911 17.9466 3.68408 17.7127 3.61845 17.4663C3.53001 17.1344 3.49486 16.7666 3.50184 16.3601C3.51532 15.5749 3.68902 14.5984 4.03435 13.4481C4.17427 12.9821 4.3614 12.4396 4.6015 11.7926L5.15467 10.3632C5.1536 10.287 5.15292 10.2154 5.15292 10.1604C5.15292 5.6047 7.58875 2.00038 12.0013 2C16.4138 2.00038 18.8494 5.60454 18.8494 10.1604C18.8494 10.2154 18.8487 10.2869 18.8477 10.3631L19.401 11.7923L19.4112 11.8191C19.636 12.4254 19.8242 12.9722 19.967 13.445C20.3145 14.5956 20.4889 15.5735 20.5018 16.361C20.5085 16.768 20.4728 17.1365 20.3837 17.4689C20.3178 17.7148 20.2228 17.9483 20.0746 18.1768C19.7976 18.6041 19.3905 18.9532 18.7974 19.0862C18.9266 19.6411 18.8523 20.2274 18.5574 20.7407Z';
+/** Temporarily replaces DSH's fallback settings glyph for the QQ Chat row. */
+function installQQSettingsIcon() {
+    const originals = new Map();
+    const apply = () => {
+        for (const button of Array.from(document.querySelectorAll('button'))) {
+            const label = button.querySelector('span[class$="_navLabel"]');
+            if (label?.textContent?.trim() !== 'QQ Chat')
+                continue;
+            if (button.querySelector('[data-dsh-qqchat-icon]'))
+                continue;
+            const icon = button.querySelector('svg[class$="_navIcon"]');
+            if (!icon)
+                continue;
+            originals.set(button, icon.cloneNode(true));
+            icon.remove();
+            const replacement = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+            replacement.setAttribute('width', '16');
+            replacement.setAttribute('height', '16');
+            replacement.setAttribute('viewBox', '0 0 24 24');
+            replacement.setAttribute('fill', 'currentColor');
+            replacement.setAttribute('aria-hidden', 'true');
+            replacement.setAttribute('data-dsh-qqchat-icon', 'true');
+            replacement.classList.add('dsh-qqchat-nav-icon');
+            const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+            path.setAttribute('d', QQ_ICON_PATH);
+            replacement.append(path);
+            button.insertBefore(replacement, label);
+        }
+    };
+    const observer = new MutationObserver(apply);
+    observer.observe(document.body, { childList: true, subtree: true });
+    apply();
+    return () => {
+        observer.disconnect();
+        for (const [button, original] of originals) {
+            const replacement = button.querySelector('[data-dsh-qqchat-icon]');
+            if (replacement)
+                replacement.replaceWith(original);
+        }
+        originals.clear();
+    };
+}
 const css = `
 .qqs{display:flex;flex-direction:column;gap:18px;color:var(--dsw-alias-label-primary);font:inherit}.qqs *{box-sizing:border-box}
 .qqsHead{display:flex;align-items:center;justify-content:space-between;gap:12px}.qqsBrand{display:flex;align-items:center;gap:10px}.qqsLogo{width:34px;height:34px;border-radius:10px;display:grid;place-items:center;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l1);font-weight:700}.qqsTitle{font-size:15px;font-weight:620}.qqMuted{font-size:12px;color:var(--dsw-alias-label-secondary);line-height:1.55}.qqStatus{display:flex;align-items:center;gap:7px;font-size:12px;color:var(--dsw-alias-label-secondary)}.qqDot{width:7px;height:7px;border-radius:50%;background:var(--dsw-alias-state-warn-primary)}.qqDot.online{background:var(--dsw-alias-state-success-primary)}

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);
@@ -26,7 +31,10 @@ export function apply(ctx, inputConfig = {}) {
     const runtime = new QQChatRuntime(ctx, db, api, auth, memory, bridge, config, logger, media);
     ctx.connection.rpc.handle('/qqchat', createQQChatRpc(runtime), { authority: 'loopback' });
     ctx.effect(() => {
-        void runtime.start().catch(error => logger.error?.(error));
+        void (async () => {
+            await bridge.ensureWorkspaceMembership();
+            await runtime.start();
+        })().catch(error => logger.error?.(error));
         return () => runtime.stop();
     }, 'dsh-qqchat runtime');
 }

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,4 +1,5 @@
 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';
@@ -21,6 +22,7 @@ export declare class DshQQBridge {
     private readonly activeAttachments;
     private readonly activeMediaReadable;
     private readonly memorySnapshots;
+    private qqWorkspace?;
     private readonly disposeEvent;
     private readonly disposeToolGate;
     private readonly disposeCommands;
@@ -29,12 +31,15 @@ export declare class DshQQBridge {
     constructor(ctx: Context, db: QQChatDatabase, memory: MemoryEngine, config: QQChatConfig, logger?: LoggerLike);
     dispose(): Promise<void>;
     ensureChatSession(chatType: ChatType, row: GroupRow | MemberRow): Promise<string>;
+    ensureWorkspaceMembership(): Promise<void>;
     recordTranscript(event: QQChatDisplayEvent, row: GroupRow | MemberRow, createSession?: boolean): Promise<string | undefined>;
     reply(message: QQNormalizedMessage, group: GroupRow | undefined, member: MemberRow, attachments?: StoredAttachmentSummary[], onTextDelta?: (delta: string) => void, isOwner?: boolean): Promise<string>;
     private onSessionEvent;
     private injectMemorySnapshot;
     private restoreMemorySnapshot;
     private ensureAgent;
+    /** Keep all QQ sessions together in one DSH Workspace using the host API. */
+    private attachToQQWorkspace;
     private isArchived;
     private rememberRoute;
     private appendDisplayIfMissing;
@@ -42,7 +47,6 @@ export declare class DshQQBridge {
     private ensureTitle;
     private tryResume;
     private agentOptions;
-    private imageRouteAvailable;
     private ensureSelection;
     private selection;
     private requestReset;
@@ -56,3 +60,5 @@ export declare class DshQQBridge {
     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[];

package/lib/session/agent-bridge.js

@@ -33,6 +33,7 @@ export class DshQQBridge {
     activeAttachments = new Map();
     activeMediaReadable = new Map();
     memorySnapshots = new Map();
+    qqWorkspace;
     disposeEvent;
     disposeToolGate;
     disposeCommands;
@@ -97,6 +98,16 @@ export class DshQQBridge {
         const { sessionId } = await this.ensureAgent(chatType, row);
         return sessionId;
     }
+    async ensureWorkspaceMembership() {
+        const sessionIds = [
+            ...this.db.listGroups().map(row => row.dsh_session_id),
+            ...this.db.listDirectChats().map(row => row.dsh_session_id),
+        ];
+        for (const sessionId of sessionIds) {
+            if (sessionId)
+                await this.attachToQQWorkspace(sessionId);
+        }
+    }
     async recordTranscript(event, row, createSession = false) {
         const existing = this.db.getChatSession(event.chatType, Number(row.id));
         if (!existing && !createSession)
@@ -104,11 +115,12 @@ export class DshQQBridge {
         const { agent, sessionId } = await this.ensureAgent(event.chatType, row);
         event.sessionId = sessionId;
         if (event.isOwner) {
-            const hasImages = event.attachments?.some(attachment => attachment.kind === 'image' && this.db.attachmentById(attachment.id)?.imageRef) === true;
-            if (!hasImages || await this.imageRouteAvailable(agent))
-                this.appendOwnerMessageIfMissing(agent.session, event);
-            else
-                this.appendDisplayIfMissing(agent.session, event);
+            // Keep owner messages as native user/message events even when they carry
+            // images. DSH now owns the image projection: visual routes receive the
+            // durable image block, while text-only routes receive its stable text
+            // placeholder. Falling back to a display-only event here would discard
+            // the owner's message semantics before DSH can apply that policy.
+            this.appendOwnerMessageIfMissing(agent.session, event);
             return sessionId;
         }
         this.appendDisplayIfMissing(agent.session, event);
@@ -157,15 +169,7 @@ export class DshQQBridge {
                     : this.memory.contextForMember(member);
                 this.injectMemorySnapshot(agent, sessionId, contextText);
             }
-            const currentText = this.memory.currentMessageText(message) + mediaPrompt(attachments);
-            const currentContent = [{ type: 'text', text: currentText }];
-            if (attachments.length && await this.imageRouteAvailable(agent)) {
-                for (const attachment of attachments) {
-                    if (attachment.kind === 'image' && attachment.imageRef) {
-                        currentContent.push({ type: 'image', attachment: attachment.imageRef });
-                    }
-                }
-            }
+            const currentContent = qqMessageContent(this.memory.currentMessageText(message), attachments);
             const current = createUserMessage({
                 source: {
                     kind: 'qq-chat', botId: String(message.accountId), chatType: message.chatType,
@@ -281,6 +285,7 @@ export class DshQQBridge {
                 this.ensureSelection(live);
                 this.ensureTitle(live.session, chatType, row);
                 this.rememberRoute(chatType, row, live, sessionId);
+                await this.attachToQQWorkspace(sessionId);
                 return { agent: live, sessionId };
             }
             const resumed = await this.tryResume(sessionId);
@@ -288,6 +293,7 @@ export class DshQQBridge {
                 this.ensureSelection(resumed.agent);
                 this.ensureTitle(resumed.agent.session, chatType, row);
                 this.rememberRoute(chatType, row, resumed.agent, sessionId);
+                await this.attachToQQWorkspace(sessionId);
                 return { agent: resumed.agent, sessionId };
             }
         }
@@ -306,8 +312,30 @@ export class DshQQBridge {
         this.db.setChatSession(chatType, Number(row.id), sessionId);
         this.ensureTitle(handle.agent.session, chatType, row);
         this.rememberRoute(chatType, row, handle.agent, sessionId);
+        await this.attachToQQWorkspace(sessionId);
         return { agent: handle.agent, sessionId };
     }
+    /** Keep all QQ sessions together in one DSH Workspace using the host API. */
+    async attachToQQWorkspace(sessionId) {
+        const registry = this.ctx.workspaceRegistry;
+        if (!registry)
+            return;
+        if (!this.qqWorkspace) {
+            this.qqWorkspace = registry.create(process.cwd(), 'QQ Chat').catch(error => {
+                this.logger.warn?.(`[dsh-qqchat] QQ Workspace 创建失败，将保留在未分组: ${error instanceof Error ? error.message : String(error)}`);
+                return undefined;
+            });
+        }
+        const workspace = await this.qqWorkspace;
+        if (!workspace)
+            return;
+        try {
+            await workspace.attachSession(SessionId(sessionId));
+        }
+        catch (error) {
+            this.logger.warn?.(`[dsh-qqchat] QQ session ${sessionId} 加入 Workspace 失败，将保留在未分组: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     isArchived(sessionId) {
         const registry = this.ctx.workspaceRegistry;
         return registry?.archivedSessionIds.includes(sessionId) ?? false;
@@ -325,7 +353,11 @@ export class DshQQBridge {
     appendDisplayIfMissing(session, event) {
         if (session.events.some(item => item.type === 'qqchat/message' && item.data.messageId === event.messageId))
             return;
-        session.append('qqchat/message', displayEventPayload(event), { ignorable: true });
+        // Keep this on the public Session.append signature. Official DSH releases
+        // do not yet expose the optional ignorable envelope marker; if an older
+        // DSH cannot restore this plugin-only event, ensureAgent falls back to a
+        // fresh Session while SQLite remains the QQ history source of truth.
+        session.append('qqchat/message', displayEventPayload(event));
     }
     appendOwnerMessageIfMissing(session, event) {
         if (session.events.some(item => {
@@ -387,18 +419,6 @@ export class DshQQBridge {
             options.maxTokens = this.config.maxTokens;
         return options;
     }
-    async imageRouteAvailable(agent) {
-        const route = this.selection(agent)?.current || { provider: agent.options.provider, model: agent.options.model };
-        if (!route.provider || !route.model)
-            return false;
-        try {
-            const info = await this.ctx.llm.resolveModelInfo(route.provider, route.model);
-            return info.inputModalities?.includes('image') === true;
-        }
-        catch {
-            return false;
-        }
-    }
     ensureSelection(agent) {
         const id = String(agent.id);
         const existing = this.selections.get(id);
@@ -593,7 +613,17 @@ function mediaPrompt(attachments) {
     if (!attachments.length)
         return '';
     const lines = attachments.map(item => `- ${item.kind}: ${item.filename} (attachment_id=${item.id}${item.quoted ? ', 引用消息附件' : ''})`);
-    return `\n\n[QQ 媒体附件]\n${lines.join('\n')}\n图片可使用 qqchat_describe_image 查看。`;
+    return `\n\n[QQ 媒体附件]\n${lines.join('\n')}\n图片由 DSH 根据当前模型能力处理；视觉模型可直接理解图片。`;
+}
+/** Build the durable DSH content for one QQ turn without pre-flighting the model. */
+export function qqMessageContent(text, attachments) {
+    const content = [{ type: 'text', text: text + mediaPrompt([...attachments]) }];
+    for (const attachment of attachments) {
+        if (attachment.kind === 'image' && attachment.imageRef) {
+            content.push({ type: 'image', attachment: attachment.imageRef });
+        }
+    }
+    return content;
 }
 function transcriptContent(event, db) {
     const attachments = event.attachments || [];

package/lib/session/registration.d.ts

@@ -0,0 +1,14 @@
+export interface SessionEventRegistrationOptions {
+    readonly argv?: readonly string[];
+    readonly dshHome?: string;
+    readonly anchors?: readonly string[];
+}
+export declare function profileNameFromArgv(argv: readonly string[]): string | undefined;
+/**
+ * Register the plugin's log-only event in every reachable dsh-session copy.
+ *
+ * DSH does not expose a public downstream event registration API yet. This
+ * small compatibility shim follows the ecosystem convention used by other
+ * DSH plugins and is intentionally idempotent and best-effort.
+ */
+export declare function registerQQChatSessionEventType(options?: SessionEventRegistrationOptions): Promise<number>;

package/lib/session/registration.js

@@ -0,0 +1,94 @@
+import { createRequire } from 'node:module';
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const QQCHAT_SESSION_EVENT_TYPE = 'qqchat/message';
+export function profileNameFromArgv(argv) {
+    const profileIndex = argv.indexOf('--profile');
+    if (profileIndex >= 0) {
+        const value = argv[profileIndex + 1];
+        if (value && !value.startsWith('-'))
+            return value;
+    }
+    const inline = argv.find(value => value.startsWith('--profile='));
+    const value = inline?.slice('--profile='.length);
+    return value && !value.startsWith('-') ? value : undefined;
+}
+/**
+ * Register the plugin's log-only event in every reachable dsh-session copy.
+ *
+ * DSH does not expose a public downstream event registration API yet. This
+ * small compatibility shim follows the ecosystem convention used by other
+ * DSH plugins and is intentionally idempotent and best-effort.
+ */
+export async function registerQQChatSessionEventType(options = {}) {
+    const argv = options.argv || process.argv;
+    const profileName = profileNameFromArgv(argv);
+    const dshHome = options.dshHome || process.env.DSH_HOME || join(homedir(), '.dsh');
+    const profileAnchors = profileName
+        ? [
+            join(dshHome, 'profiles', profileName, 'package.json'),
+            join(dshHome, 'profiles', 'package.json'),
+        ]
+        : [];
+    const anchors = [...(options.anchors || [import.meta.url, argv[1]]), ...profileAnchors].filter((anchor) => typeof anchor === 'string' && anchor.length > 0);
+    const registeredPaths = new Set();
+    let registered = 0;
+    for (const anchor of anchors) {
+        try {
+            const require = createRequire(anchor);
+            registered += await registerSessionCopy(require, registeredPaths);
+            // Persistence may resolve its own peer dependency from a different
+            // package tree. Register the copy selected by that validator too.
+            try {
+                const persistence = require.resolve('@deepseek-ai/dsh-session-persistence');
+                registered += await registerSessionCopy(createRequire(persistence), registeredPaths);
+            }
+            catch {
+                // Some minimal profiles do not ship the persistence package.
+            }
+        }
+        catch {
+            // A profile may not expose this package from one of the anchors. The
+            // other anchor can still reach the validator used by the running host.
+        }
+    }
+    return registered;
+}
+async function registerSessionCopy(require, registeredPaths) {
+    const resolved = require.resolve('@deepseek-ai/dsh-session');
+    const candidates = [resolved];
+    // The DSH development CLI can resolve workspace source through tsx while
+    // the published package resolves lib/. Register both when source exists.
+    const packageRoot = dirname(dirname(resolved));
+    candidates.push(join(packageRoot, 'src', 'index.ts'));
+    candidates.push(join(packageRoot, 'src', 'index.js'));
+    let registered = 0;
+    for (const candidate of candidates) {
+        let physical;
+        try {
+            physical = realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (registeredPaths.has(physical))
+            continue;
+        registeredPaths.add(physical);
+        try {
+            // DSH publishes ESM builds. Dynamic import also handles a CJS build and
+            // preserves the actual module instance selected by the host anchor.
+            const module = await import(pathToFileURL(physical).href);
+            if (module.KNOWN_SESSION_EVENT_TYPES?.add) {
+                module.KNOWN_SESSION_EVENT_TYPES.add(QQCHAT_SESSION_EVENT_TYPE);
+                registered += 1;
+            }
+        }
+        catch {
+            // A published package may not ship its source entry; the lib entry above
+            // remains the normal registration target.
+        }
+    }
+    return registered;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-qqchat",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "DeepSeek Harness 的 QQ 私聊/群聊插件，支持扫码授权、原生 Session、群记忆与工具权限。",
   "type": "module",
   "license": "MIT",
@@ -46,17 +46,18 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8"
+    "@deepseek-ai/dsh-attachment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-client-connection": {
@@ -73,10 +74,11 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-attachment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.2",
     "@types/node": "^22.18.0",
     "@types/qrcode": "^1.5.5",
     "@types/react": "^19.1.0",

package/src/index.ts

@@ -14,8 +14,11 @@ 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'
 import type { LoggerLike, QQChatConfigInput } from './types.js'
 
+const qqChatSessionEventRegistrations = await registerQQChatSessionEventType()
+
 export const name = 'dsh-qqchat'
 export const inject = ['connection', 'agents', 'agentDefaultModel', 'commands', 'llm', 'tools', 'workspaceRegistry'] as const
 
@@ -25,6 +28,9 @@ export function apply(ctx: Context, inputConfig: QQChatConfigInput = {}): void {
   const db = new QQChatDatabase(join(config.dataDir, 'qqchat.sqlite'))
   const baseLogger = (ctx as unknown as { logger?: LoggerLike }).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)
@@ -34,7 +40,10 @@ export function apply(ctx: Context, inputConfig: QQChatConfigInput = {}): void {
 
   ctx.connection.rpc.handle('/qqchat', createQQChatRpc(runtime), { authority: 'loopback' })
   ctx.effect(() => {
-    void runtime.start().catch(error => logger.error?.(error))
+    void (async () => {
+      await bridge.ensureWorkspaceMembership()
+      await runtime.start()
+    })().catch(error => logger.error?.(error))
     return () => runtime.stop()
   }, 'dsh-qqchat runtime')
 }

package/src/media/image-tool.ts

@@ -2,11 +2,11 @@ import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 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 function registerQQImageTool(ctx: Context, db: QQChatDatabase, isAllowed: (agentId: string, attachmentId: string) => boolean = () => true): () => void {
   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/src/session/agent-bridge.ts

@@ -39,7 +39,11 @@ interface AgentPreset { id: string }
 interface AgentPresetService { resolve(id?: string): Promise<AgentPreset>; list(): Promise<AgentPreset[]>; mount(ctx: Context, id: string): Promise<unknown>; recompose(ctx: Context, id: string): Promise<AgentPreset> }
 interface SessionPersistenceService { inspect(id: SessionId): Promise<{ meta: Session['header']; events: readonly SessionEvent[] }> }
 interface SessionTitleService { get(session: Session): unknown; rename(session: Session, title: string): unknown }
-interface WorkspaceRegistryService { archivedSessionIds: readonly string[] }
+interface WorkspaceEntity { attachSession(sessionId: SessionId): Promise<void> }
+interface WorkspaceRegistryService {
+  archivedSessionIds: readonly string[]
+  create(path: string, title?: string): Promise<WorkspaceEntity>
+}
 interface Composition { presetId?: string; setup?: AgentSetup }
 interface ActiveActor { chatType: ChatType; senderId: string }
 
@@ -62,6 +66,7 @@ export class DshQQBridge {
   private readonly activeAttachments = new Map<string, Set<string>>()
   private readonly activeMediaReadable = new Map<string, boolean>()
   private readonly memorySnapshots = new Map<string, MemorySnapshotState>()
+  private qqWorkspace?: Promise<WorkspaceEntity | undefined>
   private readonly disposeEvent: () => void
   private readonly disposeToolGate: () => void
   private readonly disposeCommands: () => void
@@ -122,15 +127,28 @@ export class DshQQBridge {
     return sessionId
   }
 
+  async ensureWorkspaceMembership(): Promise<void> {
+    const sessionIds = [
+      ...this.db.listGroups().map(row => row.dsh_session_id),
+      ...this.db.listDirectChats().map(row => row.dsh_session_id),
+    ]
+    for (const sessionId of sessionIds) {
+      if (sessionId) await this.attachToQQWorkspace(sessionId)
+    }
+  }
+
   async recordTranscript(event: QQChatDisplayEvent, row: GroupRow | MemberRow, createSession = false): Promise<string | undefined> {
     const existing = this.db.getChatSession(event.chatType, Number(row.id))
     if (!existing && !createSession) return undefined
     const { agent, sessionId } = await this.ensureAgent(event.chatType, row)
     event.sessionId = sessionId
     if (event.isOwner) {
-      const hasImages = event.attachments?.some(attachment => attachment.kind === 'image' && this.db.attachmentById(attachment.id)?.imageRef) === true
-      if (!hasImages || await this.imageRouteAvailable(agent)) this.appendOwnerMessageIfMissing(agent.session, event)
-      else this.appendDisplayIfMissing(agent.session, event)
+      // Keep owner messages as native user/message events even when they carry
+      // images. DSH now owns the image projection: visual routes receive the
+      // durable image block, while text-only routes receive its stable text
+      // placeholder. Falling back to a display-only event here would discard
+      // the owner's message semantics before DSH can apply that policy.
+      this.appendOwnerMessageIfMissing(agent.session, event)
       return sessionId
     }
     this.appendDisplayIfMissing(agent.session, event)
@@ -178,15 +196,7 @@ export class DshQQBridge {
         this.injectMemorySnapshot(agent, sessionId, contextText)
       }
 
-      const currentText = this.memory.currentMessageText(message) + mediaPrompt(attachments)
-      const currentContent: ContentBlock[] = [{ type: 'text', text: currentText }]
-      if (attachments.length && await this.imageRouteAvailable(agent)) {
-        for (const attachment of attachments) {
-          if (attachment.kind === 'image' && attachment.imageRef) {
-            currentContent.push({ type: 'image', attachment: attachment.imageRef })
-          }
-        }
-      }
+      const currentContent = qqMessageContent(this.memory.currentMessageText(message), attachments)
       const current = createUserMessage({
         source: {
           kind: 'qq-chat', botId: String(message.accountId), chatType: message.chatType,
@@ -296,6 +306,7 @@ export class DshQQBridge {
         this.ensureSelection(live)
         this.ensureTitle(live.session, chatType, row)
         this.rememberRoute(chatType, row, live, sessionId)
+        await this.attachToQQWorkspace(sessionId)
         return { agent: live, sessionId }
       }
       const resumed = await this.tryResume(sessionId)
@@ -303,6 +314,7 @@ export class DshQQBridge {
         this.ensureSelection(resumed.agent)
         this.ensureTitle(resumed.agent.session, chatType, row)
         this.rememberRoute(chatType, row, resumed.agent, sessionId)
+        await this.attachToQQWorkspace(sessionId)
         return { agent: resumed.agent, sessionId }
       }
     }
@@ -322,9 +334,29 @@ export class DshQQBridge {
     this.db.setChatSession(chatType, Number(row.id), sessionId)
     this.ensureTitle(handle.agent.session, chatType, row)
     this.rememberRoute(chatType, row, handle.agent, sessionId)
+    await this.attachToQQWorkspace(sessionId)
     return { agent: handle.agent, sessionId }
   }
 
+  /** Keep all QQ sessions together in one DSH Workspace using the host API. */
+  private async attachToQQWorkspace(sessionId: string): Promise<void> {
+    const registry = (this.ctx as unknown as { workspaceRegistry?: WorkspaceRegistryService }).workspaceRegistry
+    if (!registry) return
+    if (!this.qqWorkspace) {
+      this.qqWorkspace = registry.create(process.cwd(), 'QQ Chat').catch(error => {
+        this.logger.warn?.(`[dsh-qqchat] QQ Workspace 创建失败，将保留在未分组: ${error instanceof Error ? error.message : String(error)}`)
+        return undefined
+      })
+    }
+    const workspace = await this.qqWorkspace
+    if (!workspace) return
+    try {
+      await workspace.attachSession(SessionId(sessionId))
+    } catch (error) {
+      this.logger.warn?.(`[dsh-qqchat] QQ session ${sessionId} 加入 Workspace 失败，将保留在未分组: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
   private isArchived(sessionId: string): boolean {
     const registry = (this.ctx as unknown as { workspaceRegistry?: WorkspaceRegistryService }).workspaceRegistry
     return registry?.archivedSessionIds.includes(sessionId) ?? false
@@ -340,7 +372,11 @@ export class DshQQBridge {
 
   private appendDisplayIfMissing(session: Session, event: QQChatDisplayEvent): void {
     if (session.events.some(item => item.type === 'qqchat/message' && item.data.messageId === event.messageId)) return
-    session.append('qqchat/message', displayEventPayload(event), { ignorable: true })
+    // Keep this on the public Session.append signature. Official DSH releases
+    // do not yet expose the optional ignorable envelope marker; if an older
+    // DSH cannot restore this plugin-only event, ensureAgent falls back to a
+    // fresh Session while SQLite remains the QQ history source of truth.
+    session.append('qqchat/message', displayEventPayload(event))
   }
 
   private appendOwnerMessageIfMissing(session: Session, event: QQChatDisplayEvent): void {
@@ -401,15 +437,6 @@ export class DshQQBridge {
     return options
   }
 
-  private async imageRouteAvailable(agent: AgentHandle['agent']): Promise<boolean> {
-    const route = this.selection(agent)?.current || { provider: agent.options.provider, model: agent.options.model }
-    if (!route.provider || !route.model) return false
-    try {
-      const info = await this.ctx.llm.resolveModelInfo(route.provider, route.model)
-      return info.inputModalities?.includes('image') === true
-    } catch { return false }
-  }
-
   private ensureSelection(agent: AgentHandle['agent']): ModelSelectionRef | undefined {
     const id = String(agent.id)
     const existing = this.selections.get(id)
@@ -598,7 +625,18 @@ export class DshQQBridge {
 function mediaPrompt(attachments: StoredAttachmentSummary[]): string {
   if (!attachments.length) return ''
   const lines = attachments.map(item => `- ${item.kind}: ${item.filename} (attachment_id=${item.id}${item.quoted ? ', 引用消息附件' : ''})`)
-  return `\n\n[QQ 媒体附件]\n${lines.join('\n')}\n图片可使用 qqchat_describe_image 查看。`
+  return `\n\n[QQ 媒体附件]\n${lines.join('\n')}\n图片由 DSH 根据当前模型能力处理；视觉模型可直接理解图片。`
+}
+
+/** Build the durable DSH content for one QQ turn without pre-flighting the model. */
+export function qqMessageContent(text: string, attachments: readonly StoredAttachmentSummary[]): ContentBlock[] {
+  const content: ContentBlock[] = [{ type: 'text', text: text + mediaPrompt([...attachments]) }]
+  for (const attachment of attachments) {
+    if (attachment.kind === 'image' && attachment.imageRef) {
+      content.push({ type: 'image', attachment: attachment.imageRef })
+    }
+  }
+  return content
 }
 
 function transcriptContent(event: QQChatDisplayEvent, db: QQChatDatabase): ContentBlock[] {

package/src/session/registration.ts

@@ -0,0 +1,102 @@
+import { createRequire } from 'node:module'
+import { realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const QQCHAT_SESSION_EVENT_TYPE = 'qqchat/message'
+
+interface KnownEventTypesModule {
+  KNOWN_SESSION_EVENT_TYPES?: { add(type: string): unknown }
+}
+
+export interface SessionEventRegistrationOptions {
+  readonly argv?: readonly string[]
+  readonly dshHome?: string
+  readonly anchors?: readonly string[]
+}
+
+export function profileNameFromArgv(argv: readonly string[]): string | undefined {
+  const profileIndex = argv.indexOf('--profile')
+  if (profileIndex >= 0) {
+    const value = argv[profileIndex + 1]
+    if (value && !value.startsWith('-')) return value
+  }
+  const inline = argv.find(value => value.startsWith('--profile='))
+  const value = inline?.slice('--profile='.length)
+  return value && !value.startsWith('-') ? value : undefined
+}
+
+/**
+ * Register the plugin's log-only event in every reachable dsh-session copy.
+ *
+ * DSH does not expose a public downstream event registration API yet. This
+ * small compatibility shim follows the ecosystem convention used by other
+ * DSH plugins and is intentionally idempotent and best-effort.
+ */
+export async function registerQQChatSessionEventType(options: SessionEventRegistrationOptions = {}): Promise<number> {
+  const argv = options.argv || process.argv
+  const profileName = profileNameFromArgv(argv)
+  const dshHome = options.dshHome || process.env.DSH_HOME || join(homedir(), '.dsh')
+  const profileAnchors = profileName
+    ? [
+        join(dshHome, 'profiles', profileName, 'package.json'),
+        join(dshHome, 'profiles', 'package.json'),
+      ]
+    : []
+  const anchors = [...(options.anchors || [import.meta.url, argv[1]]), ...profileAnchors].filter(
+    (anchor): anchor is string => typeof anchor === 'string' && anchor.length > 0,
+  )
+  const registeredPaths = new Set<string>()
+  let registered = 0
+
+  for (const anchor of anchors) {
+    try {
+      const require = createRequire(anchor)
+      registered += await registerSessionCopy(require, registeredPaths)
+      // Persistence may resolve its own peer dependency from a different
+      // package tree. Register the copy selected by that validator too.
+      try {
+        const persistence = require.resolve('@deepseek-ai/dsh-session-persistence')
+        registered += await registerSessionCopy(createRequire(persistence), registeredPaths)
+      } catch {
+        // Some minimal profiles do not ship the persistence package.
+      }
+    } catch {
+      // A profile may not expose this package from one of the anchors. The
+      // other anchor can still reach the validator used by the running host.
+    }
+  }
+
+  return registered
+}
+
+async function registerSessionCopy(require: NodeRequire, registeredPaths: Set<string>): Promise<number> {
+  const resolved = require.resolve('@deepseek-ai/dsh-session')
+  const candidates = [resolved]
+  // The DSH development CLI can resolve workspace source through tsx while
+  // the published package resolves lib/. Register both when source exists.
+  const packageRoot = dirname(dirname(resolved))
+  candidates.push(join(packageRoot, 'src', 'index.ts'))
+  candidates.push(join(packageRoot, 'src', 'index.js'))
+  let registered = 0
+  for (const candidate of candidates) {
+    let physical: string
+    try { physical = realpathSync(candidate) } catch { continue }
+    if (registeredPaths.has(physical)) continue
+    registeredPaths.add(physical)
+    try {
+      // DSH publishes ESM builds. Dynamic import also handles a CJS build and
+      // preserves the actual module instance selected by the host anchor.
+      const module = await import(pathToFileURL(physical).href) as KnownEventTypesModule
+      if (module.KNOWN_SESSION_EVENT_TYPES?.add) {
+        module.KNOWN_SESSION_EVENT_TYPES.add(QQCHAT_SESSION_EVENT_TYPE)
+        registered += 1
+      }
+    } catch {
+      // A published package may not ship its source entry; the lib entry above
+      // remains the normal registration target.
+    }
+  }
+  return registered
+}