dsh-qqchat 0.2.2 → 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).

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>

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/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,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';
@@ -42,7 +43,6 @@ export declare class DshQQBridge {
     private ensureTitle;
     private tryResume;
     private agentOptions;
-    private imageRouteAvailable;
     private ensureSelection;
     private selection;
     private requestReset;
@@ -56,3 +56,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

@@ -104,11 +104,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 +158,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,
@@ -325,7 +318,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 +384,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 +578,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.3",
   "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)

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

@@ -128,9 +128,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)
@@ -178,15 +181,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,
@@ -340,7 +335,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 +400,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 +588,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
+}