dsh-qqchat 0.2.1 → 0.2.3

package/lib/session/agent-bridge.js

@@ -1,15 +1,19 @@
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { installModelSelection } from '@deepseek-ai/dsh-agent';
+import { resolveSessionPreset } from '@deepseek-ai/dsh-agent-presets';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SessionId } from '@deepseek-ai/dsh-session';
 import '../shared/augmentations.js';
 import { defaultRuntimeSettings } from '../config.js';
 import { registerQQImageTool } from '../media/image-tool.js';
 import { registerQQMediaTools } from '../media/media-tools.js';
-import { dispatchQQCommand, qqCommandText } from '../commands/dispatch.js';
+import { dispatchQQCommand, qqCommandText, slashCommandName } from '../commands/dispatch.js';
 import { MEMORY_SNAPSHOT_TTL_MS, memorySnapshotHash, restoreMemorySnapshotState, shouldRefreshMemorySnapshot } from './memory-snapshot.js';
 const DSH_RUNTIME_CONTEXT_SOURCE = '@deepseek-ai/dsh-system-prompt';
+export function resolveQQSessionPreset(header, events) {
+    return resolveSessionPreset({ header, events });
+}
 const MEDIA_TOOL_NAMES = new Set(['qqchat_describe_image', 'qqchat_read_file', 'qqchat_media_info']);
 const packageMetadata = createRequire(import.meta.url)('../../package.json');
 const PLUGIN_VERSION = packageMetadata.version || 'unknown';
@@ -31,7 +35,6 @@ export class DshQQBridge {
     memorySnapshots = new Map();
     disposeEvent;
     disposeToolGate;
-    disposeBootstrapGate;
     disposeCommands;
     disposeImageTool;
     disposeMediaTools;
@@ -42,11 +45,6 @@ export class DshQQBridge {
         this.config = config;
         this.logger = logger;
         this.disposeEvent = ctx.on('session/event', (session, event) => this.onSessionEvent(session, event));
-        this.disposeBootstrapGate = ctx.on('agent/pre-step', async ({ messages }, next) => {
-            if (messages.some(message => message.source.kind === 'qq-chat-bootstrap'))
-                return { kind: 'reject' };
-            return next();
-        });
         this.disposeToolGate = ctx.on('tools/pre-execute', async (exec, next) => {
             const agent = exec.agent;
             if (!agent)
@@ -75,7 +73,6 @@ export class DshQQBridge {
     }
     async dispose() {
         this.disposeEvent();
-        this.disposeBootstrapGate();
         this.disposeToolGate();
         this.disposeImageTool();
         this.disposeMediaTools();
@@ -107,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);
@@ -131,6 +129,17 @@ export class DshQQBridge {
                 if (commandText !== undefined) {
                     if (!commands)
                         return '当前 DSH profile 未加载命令系统，请重启并确认使用了最新插件。';
+                    // Preset discovery/selection is a pre-session operation. Running it
+                    // through DSH's native command executor would append command/run and
+                    // make the blank Session ineligible for the very preset it lists.
+                    // Keep the native registration for Web, but handle QQ directly.
+                    if (slashCommandName(commandText) === 'qqpreset' && (message.chatType !== 'group' || isOwner)) {
+                        const prefix = '/qqpreset';
+                        const result = await this.presetCommand(agent, commandText.slice(prefix.length).trim());
+                        if (this.pendingResets.delete(String(sessionId)))
+                            await this.resetSession(message.chatType, row);
+                        return result.text || '';
+                    }
                     const command = await dispatchQQCommand(commands, agent, commandText, { chatType: message.chatType, isOwner });
                     if (command.handled) {
                         if (this.pendingResets.delete(String(sessionId)))
@@ -149,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,
@@ -273,7 +274,6 @@ export class DshQQBridge {
                 this.ensureSelection(live);
                 this.ensureTitle(live.session, chatType, row);
                 this.rememberRoute(chatType, row, live, sessionId);
-                await this.ensureVisible(live);
                 return { agent: live, sessionId };
             }
             const resumed = await this.tryResume(sessionId);
@@ -281,7 +281,6 @@ export class DshQQBridge {
                 this.ensureSelection(resumed.agent);
                 this.ensureTitle(resumed.agent.session, chatType, row);
                 this.rememberRoute(chatType, row, resumed.agent, sessionId);
-                await this.ensureVisible(resumed.agent);
                 return { agent: resumed.agent, sessionId };
             }
         }
@@ -300,7 +299,6 @@ 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.ensureVisible(handle.agent);
         return { agent: handle.agent, sessionId };
     }
     isArchived(sessionId) {
@@ -317,15 +315,13 @@ export class DshQQBridge {
         else
             this.memory.setMemberRoute(Number(row.id), provider, model, sessionId);
     }
-    async ensureVisible(agent) {
-        if (agent.session.events.some(event => event.type === 'turn/start'))
-            return;
-        agent.followup(createUserMessage({ source: { kind: 'qq-chat-bootstrap', plugin: 'dsh-qqchat' }, content: [{ type: 'text', text: 'Activate QQ Chat workspace session.' }] }));
-        await agent.whenIdle();
-    }
     appendDisplayIfMissing(session, event) {
         if (session.events.some(item => item.type === 'qqchat/message' && item.data.messageId === event.messageId))
             return;
+        // 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) {
@@ -363,7 +359,7 @@ export class DshQQBridge {
     }
     async tryResume(sessionId) {
         try {
-            const composition = await this.composition();
+            const composition = await this.composition(sessionId);
             const handle = await this.ctx.agents.resume({ resumeSessionId: SessionId(sessionId), agentOptions: this.agentOptions(), setup: composition.setup });
             if (!handle.agent.session.header.cwd) {
                 await handle.dispose();
@@ -388,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);
@@ -451,7 +435,7 @@ export class DshQQBridge {
                 .map(command => `/${command.name}${command.input?.hint ? ` ${command.input.hint}` : ''} — ${command.description}`),
             '',
             'QQChat 会话',
-            ...commands.filter(command => ['qqnew', 'qqreset', 'qqclear', 'qqmodel', 'qqstop', 'qqstatus'].includes(command.name))
+            ...commands.filter(command => ['qqnew', 'qqreset', 'qqclear', 'qqmodel', 'qqpreset', 'qqstop', 'qqstatus'].includes(command.name))
                 .map(command => `/${command.name}${command.input?.hint ? ` ${command.input.hint}` : ''} — ${command.description}`),
             '',
             'QQChat 工具',
@@ -468,6 +452,7 @@ export class DshQQBridge {
             register('qqreset', '开始新会话（/qqnew 别名）', invocation => { this.requestReset(String(invocation.agent.id)); return { kind: 'success', text: '已开启新会话，下一条消息将进入新的 Session。' }; }),
             register('qqclear', '开始新会话（/qqnew 别名）', invocation => { this.requestReset(String(invocation.agent.id)); return { kind: 'success', text: '已开启新会话，下一条消息将进入新的 Session。' }; }),
             register('qqmodel', '查看或切换当前会话模型', invocation => this.modelCommand(invocation), '[provider/]model'),
+            register('qqpreset', '查看或切换当前 Session 的 Agent Preset', invocation => this.presetCommand(invocation.agent, invocation.rawInput.trim()), 'preset'),
             register('qqstop', '中止当前生成', invocation => {
                 if (invocation.agent.status !== 'running')
                     return { kind: 'success', text: '当前没有进行中的生成。' };
@@ -512,6 +497,31 @@ export class DshQQBridge {
         this.routes.set(String(agent.id), { provider, model });
         return { kind: 'success', text: `模型已切换：${provider}/${model}\n对话上下文保留，下一轮生效。` };
     }
+    async presetCommand(agent, requested) {
+        const getService = this.ctx.get;
+        const presets = getService?.call(this.ctx, 'agentPresets');
+        if (!presets)
+            return { kind: 'error', text: '当前 DSH profile 未加载 Agent Preset 系统。' };
+        if (!requested) {
+            const available = await presets.list();
+            return { kind: 'success', text: available.length ? `可用 Agent Preset：\n${available.map(preset => `/qqpreset ${preset.id}`).join('\n')}` : '当前没有可用 Agent Preset。' };
+        }
+        if (agent.session.events.some(event => event.type === 'turn/start')) {
+            return { kind: 'error', text: '当前 Session 已经开始对话，DSH 不允许更换 Agent Preset。请先使用 /qqnew 开启新 Session。' };
+        }
+        try {
+            const preset = await presets.recompose(agent.ctx, requested);
+            agent.session.append('agent-preset/selected', { agentPreset: preset.id });
+            return { kind: 'success', text: `当前 Session 已切换到 Agent Preset：${preset.id}` };
+        }
+        catch {
+            const available = await presets.list().catch(() => []);
+            const availableText = available.length
+                ? `当前可用：${available.map(preset => preset.id).join('、')}`
+                : '当前没有可用 Agent Preset。';
+            return { kind: 'error', text: `无法切换 Agent Preset「${requested}」：该 preset 不存在、已删除或格式无效。\n${availableText}` };
+        }
+    }
     statusCommand(agent) {
         const current = this.selection(agent)?.current;
         const messages = agent.session.events.filter(event => event.type === 'user/message' || event.type === 'assistant/message').length;
@@ -521,14 +531,41 @@ export class DshQQBridge {
             text: ['📊 Session 状态', `Session：${String(agent.id)}`, `状态：${agent.status === 'running' ? '生成中' : '空闲'}`, `模型：${current ? `${current.provider}/${current.model}` : '未知'}`, `消息数：${messages}`, `最后事件：${last?.type || '无'}`].join('\n'),
         };
     }
-    async composition() {
+    async composition(sessionId) {
         const getService = this.ctx.get;
         const presets = getService?.call(this.ctx, 'agentPresets');
         if (!presets)
             return {};
-        const preset = await presets.resolve(this.config.agentPreset);
+        const persisted = sessionId ? await this.persistedPreset(sessionId) : undefined;
+        const requested = persisted || this.config.agentPreset;
+        let preset;
+        try {
+            preset = await presets.resolve(requested);
+        }
+        catch (error) {
+            const available = await presets.list();
+            const fallback = available[0];
+            if (!fallback)
+                throw error;
+            this.logger.warn?.(`[dsh-qqchat] Agent Preset「${requested || '默认'}」不可用，已降级到「${fallback.id}」`);
+            preset = await presets.resolve(fallback.id);
+        }
         return { presetId: preset.id, setup: async (agentCtx) => { await presets.mount(agentCtx, preset.id); } };
     }
+    async persistedPreset(sessionId) {
+        const getService = this.ctx.get;
+        const persistence = getService?.call(this.ctx, 'sessionPersistence');
+        if (!persistence)
+            return undefined;
+        try {
+            const inspection = await persistence.inspect(SessionId(sessionId));
+            return resolveQQSessionPreset(inspection.meta, inspection.events);
+        }
+        catch (error) {
+            this.logger.debug?.(`[dsh-qqchat] persisted preset lookup skipped: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
     serial(key, task) {
         const previous = this.locks.get(key) || Promise.resolve();
         const current = previous.catch(() => undefined).then(task);
@@ -541,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/lib/session/runtime.js

@@ -163,6 +163,9 @@ export class QQChatRuntime {
         const id = Number(account.id);
         if (this.gateways.has(id))
             return;
+        // QR binding can replace the secret for an existing account id. Never
+        // carry a token obtained with the previous secret into the new Gateway.
+        this.api.clearToken(id);
         const gateway = new QQGateway(account, this.db, this.api, message => this.onIncoming(message), this.logger);
         this.gateways.set(id, gateway);
         gateway.start();

package/lib/shared/augmentations.d.ts

@@ -25,10 +25,6 @@ declare module '@deepseek-ai/dsh-llm' {
             form: 'notice';
             summary: string;
         };
-        'qq-chat-bootstrap': {
-            kind: 'qq-chat-bootstrap';
-            plugin: 'dsh-qqchat';
-        };
     }
 }
 declare module '@deepseek-ai/dsh-session/types' {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-qqchat",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "DeepSeek Harness 的 QQ 私聊/群聊插件，支持扫码授权、原生 Session、群记忆与工具权限。",
   "type": "module",
   "license": "MIT",
@@ -46,16 +46,18 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^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": {
@@ -72,9 +74,11 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent-default-model": "^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/gateway/api.ts

@@ -75,12 +75,16 @@ export class QQApiClient {
     return data.access_token
   }
 
-  async gatewayUrl(account: AccountRow): Promise<string> {
+  async gatewayUrl(account: AccountRow, retry = true): Promise<string> {
     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<QQGatewayPayload>(response)
     if (!response.ok || !data?.url) throw new Error(`QQ gateway 获取失败: HTTP ${response.status}`)
     return data.url

package/src/gateway/gateway.ts

@@ -71,7 +71,11 @@ export class QQGateway {
   }
 
   private async connectOnce(): Promise<void> {
-    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<void>((resolve, reject) => {
       const ws = new WebSocket(url)
       this.ws = ws

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' },
     },