dsh-qqchat 0.2.0 → 0.2.2

package/README.en.md

@@ -31,16 +31,18 @@
 | --- | --- | --- |
 | QQ group and direct chat | Receives group and C2C messages | One isolated DSH Session per group or direct peer |
 | QR connection | Binds an official QQ Bot from **Settings -> QQ Chat** | Cancel the binding and scan again when needed |
+| Manual connection | Connects with AppID and AppSecret from the settings page | Useful for headless servers or QR failures; the secret is sent only to the Host |
 | Group receive modes | Auto reply, Mention only or Silent record | Silent record stores messages without waking the Agent |
 | Message formats | Smart, Markdown or Plain compatibility | Group and direct-chat formats are configured separately; groups default to Plain compatibility |
 | Direct-chat streaming | Optionally uses QQ's official streaming message API for private chats | Private chats only; Plain compatibility disables it automatically; some clients may not display streaming |
 | Quotes and mentions | Preserves quoted messages and resolves QQ mentions to display names | Stable IDs remain in metadata |
-| Memory system | Stores group, member and direct-user memory | Can be disabled; disabling does not delete existing memory |
+| Memory system | Stores group, member and direct-user memory; user memory can be reused across groups under the same Bot | Group relationships and group events stay scoped; can be disabled |
 | Memory reflection | Converts recent daily notes into long-term memory | Runs asynchronously after idle or batch thresholds |
 | Media and file permissions | Separately controls receiving media, reading attachments, and regular tools | Owner and direct chats are unrestricted by default |
-| Tool permissions | Separately controls whether group members may use regular Agent tools | Owner is matched by stable user ID |
+| Permission management | Separately controls group-member tools, media reading and file receiving | Owner is matched by stable user ID |
 | Native DSH commands | Runs `/compact`, `/goal`, `/plan`, `/qqmodel`, `/qqstatus` and more directly from QQ | Commands do not go through the model; `/qqhelp` lists the full set |
 | Native DSH UI | Uses the normal Session list, Conversation surface and composer styling | QQ Sessions remain ungrouped in DSH |
+| Session presets | Each QQ Session can use DSH's native Agent Preset mechanism | The plugin default applies only to new Sessions; a Session's own selection is persisted |
 | Diagnostics | Shows plugin logs in Settings | Useful for connection and delivery troubleshooting |
 
 ## How to use
@@ -67,7 +69,7 @@
     <td width="50%" valign="top">
       <img src="./docs/assets/记忆系统.jpg" width="100%" alt="QQ Chat memory system">
       <h3>Memory system</h3>
-      <p>The plugin maintains separate memory for groups, members and direct users. Member memory supports profiles, group nicknames, historical nicknames, behavior patterns and long-term notes; recent messages are organized asynchronously. Memory is refreshed as Session context when needed, and can be disabled without deleting stored data.</p>
+      <p>The plugin maintains separate memory for groups, members and direct users. Under the same Bot, user memory is reusable across groups by stable user ID; group relationships and group events remain scoped to their original group. Member memory supports profiles, group nicknames, historical nicknames, behavior patterns and long-term notes; recent messages are organized asynchronously. Memory is refreshed as Session context when needed, and can be disabled without deleting stored data.</p>
     </td>
   </tr>
 </table>
@@ -80,6 +82,8 @@
 4. Authorize the desired official Bot.
 5. The Gateway starts automatically. Use **Cancel connection** before scanning again if you need to bind another Bot.
 
+If QR authorization is inconvenient, choose **Manual configuration** and enter the AppID and AppSecret from the QQ Open Platform. Select the sandbox environment when needed. The plugin validates the credentials before saving them and starting the Gateway.
+
 The Host decrypts and stores the AppSecret in the local plugin database. The temporary QR AES key never travels through the browser Client RPC.
 
 ### Chat in QQ
@@ -115,7 +119,7 @@ npx @deepseek-ai/dsh --profile web
 Before npm publication, install the branch directly from GitHub:
 
 ```bash
-npx @deepseek-ai/dsh plugin --profile qqchat add @deepseek-ai/dsh-web-app "git+ssh://git@github.com/Coffeiz/dsh-qqchat.git#agent/typescript-migration"
+npx @deepseek-ai/dsh plugin --profile qqchat add @deepseek-ai/dsh-web-app dsh-qqchat
 npx @deepseek-ai/dsh --profile qqchat
 ```
 
@@ -142,7 +146,7 @@ Groups default to Plain compatibility format. Group and direct-chat formats can
 
 ## Commands
 
-Messages beginning with `/` are handled directly by the command system and are not sent to the model. Native DSH commands keep their original names; QQChat commands use the `qq` prefix. In a group, write `@Bot /help` or `@Bot /qqhelp`.
+Messages beginning with `/` are handled directly by the command system and are not sent to the model. Native DSH commands keep their original names; QQChat commands use the `qq` prefix. In a group, write `@Bot /qqhelp`.
 
 | Command | Purpose |
 | --- | --- |
@@ -150,6 +154,7 @@ Messages beginning with `/` are handled directly by the command system and are n
 | `/qqnew`, `/qqreset`, `/qqclear` | Keep the old Session and start a new one on the next message |
 | `/compact` | Compact older conversation history |
 | `/qqmodel [provider/]model` | Show or switch the current Session model |
+| `/qqpreset [preset]` | List or switch the Agent Preset for the current blank Session; start a new Session after conversation begins |
 | `/qqstop` | Stop the current generation |
 | `/qqstatus` | Show Session, model and generation status |
 | `/qqping` | Check QQChat connectivity |
@@ -185,11 +190,15 @@ QQ Chat stores:
 
 Reflection runs asynchronously after the chat is idle or enough messages have accumulated. The **QQ Memory** action at the top of a QQ Session shows group and member memory. Memory snapshots refresh when a Session starts, the memory context expires, or the Session is compacted; continuous conversation does not repeatedly write the full memory. Enabled memory may reduce context-cache hit rate or increase input tokens, and can be disabled under **Settings -> QQ Chat -> Memory system** without deleting stored data.
 
-## Tool permissions
+## Permission management
 
-When **Group members can use tools** is enabled, group-triggered Agent turns may use the tools exposed by the current preset. When disabled, only the configured Owner stable ID may execute tools; other group members can still chat normally.
+The settings page keeps media/file permissions separate from regular Agent-tool permissions:
 
-Owner matching uses a stable QQ user ID, not a nickname.
+- **Receive group-member media/files** controls whether images, files, audio and video are downloaded, stored and shown in the Session.
+- **Allow group members to read media/files** controls whether a group member's Agent turn may call QQChat media tools for the current attachment.
+- **Group members can use tools** controls whether group members may use regular Agent tools exposed by the current preset.
+
+When regular tools or media reading are disabled, group members can still send normal text and receive replies. Owner matching uses a stable QQ user ID, not a nickname.
 
 ## Message display
 
@@ -201,10 +210,14 @@ QQ conversations use DSH's default Conversation UI:
 - QQ `@` mentions are converted to usernames when available.
 - The DSH Session composer can proactively send messages to QQ.
 
+## Session presets
+
+QQ Sessions use DSH's native Agent Preset mechanism. The preset configured for the plugin is only the default for new QQ Sessions. When a preset is selected for a blank Session in DSH Web, the selection is persisted with that Session and takes priority when the Session is resumed after a restart. You can also send `/qqpreset <preset>` as the first QQ message for that Session. Once a conversation has started, DSH locks the preset; use `/qqnew` to start another Session. The plugin does not copy DSH presets, tools or the AgentLoop.
+
 ## Notes
 
 - An official QQ Bot is required; personal QQ account login is not supported.
-- `0.2.0` is still being refined; test with a dedicated Bot and group first.
+- `0.2.1` 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.
 
@@ -217,15 +230,12 @@ QR authorization and connection
 Group receive mode
 Group and direct-chat reply formats
 Memory system [on/off]
-Media and file permissions and regular tool permissions are independent settings:
-
-- **Receive group-member media/files** controls whether images, files, audio, and video are downloaded, stored, and shown in the session.
-- **Allow group members to read media/files** controls whether their Agent turns may call QQChat media tools for the current attachment.
-- **Group members can use tools** controls access to regular Agent tools.
 Owner stable ID
 Diagnostics and logs
 ```
 
+Media/file permissions and regular tool permissions are independent settings. See [Permission management](#permission-management) for their behavior.
+
 The Settings page does not contain chat lists, transcripts or memory browsing. Those remain in the normal DSH Session and Conversation surfaces.
 
 ## Persistence and memory scopes
@@ -244,7 +254,7 @@ Memory scopes are isolated as follows:
 - **Member:** typed profile, pattern, summary, daily and long-term memory for one stable sender.
 - **Direct chat:** uses the member scope for that QQ user.
 
-The same stable sender may retain member memory across groups under the same Bot. Group relationships and group-specific facts never cross group scopes. Reflection runs after roughly 120 seconds of inactivity or 20 unreflected messages, and can also compress older daily records after the configured thresholds.
+The same stable sender may retain user memory across groups under the same Bot. Group relationships and group-specific facts never cross group scopes, and different Bots keep separate user-memory scopes. Reflection runs after roughly 120 seconds of inactivity or 20 unreflected messages, and can also compress older daily records after the configured thresholds.
 
 ## Development
 

package/README.md

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

package/client-src/settings.cts

@@ -15,6 +15,10 @@ export function QQSettings({ rpc }: { rpc: Rpc }) {
   const [members, setMembers] = useState<KnownMember[]>(() => qqSettingsCache?.members || [])
   const [loading, setLoading] = useState(() => qqSettingsCache === undefined)
   const [auth, setAuth] = useState<{ taskId: string; qrDataUrl: string } | null>(null)
+  const [connectionMode, setConnectionMode] = useState<'qr' | 'manual'>('qr')
+  const [manualAppId, setManualAppId] = useState('')
+  const [manualAppSecret, setManualAppSecret] = useState('')
+  const [manualSandbox, setManualSandbox] = useState(false)
   const [logs, setLogs] = useState<PluginLog[] | null>(null)
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState('')
@@ -78,6 +82,15 @@ export function QQSettings({ rpc }: { rpc: Rpc }) {
     setBusy(true)
     try { setAuth(await call<{ taskId: string; qrDataUrl: string }>(rpc, 'auth/start')); setError('') } catch (err) { setError(err instanceof Error ? err.message : String(err)) } finally { setBusy(false) }
   }
+  const connectManual = async () => {
+    setBusy(true)
+    try {
+      await call(rpc, 'account/manual-connect', { appId: manualAppId, appSecret: manualAppSecret, sandbox: manualSandbox })
+      setManualAppSecret('')
+      await refresh()
+      setError('')
+    } catch (err) { setError(err instanceof Error ? err.message : String(err)) } finally { setBusy(false) }
+  }
   const disconnect = async () => {
     if (!account) return
     setBusy(true)
@@ -128,7 +141,24 @@ export function QQSettings({ rpc }: { rpc: Rpc }) {
     h('div', { className: 'qqStatus' }, loading ? '加载中…' : account ? (account.gatewayStatus === 'online' ? '已连接' : '已授权') : '未连接', account && h(Button, { size: 'sm', variant: 'outline', disabled: busy, onClick: () => void disconnect() }, '取消连接')))
 
   if (loading) return h('div', { className: 'qqs' }, head, h('div', { className: 'qqMuted' }, '正在读取 QQ Chat 设置…'))
-  if (!account) return h('div', { className: 'qqs' }, head, error && h('div', { className: 'qqError' }, error), h('div', { className: 'qqConnect' }, h('div', { className: 'qqsTitle' }, auth ? '使用 QQ 扫码授权' : '连接 QQ Bot'), h('div', { className: 'qqMuted' }, '扫码和凭据解密都在 DSH Host 侧完成。'), auth && h('div', { className: 'qqQr' }, h('img', { src: auth.qrDataUrl, alt: 'QQ 授权二维码' })), h(Button, { variant: 'primary', disabled: busy, onClick: () => void startAuth() }, auth ? '重新生成二维码' : '扫码连接')))
+  if (!account) {
+    const modeButtons = h('div', { className: 'qqChoiceButtons' },
+      h(Button, { size: 'sm', variant: connectionMode === 'qr' ? 'primary' : 'outline', onClick: () => { setConnectionMode('qr'); setError('') } }, '扫码连接'),
+      h(Button, { size: 'sm', variant: connectionMode === 'manual' ? 'primary' : 'outline', onClick: () => { setConnectionMode('manual'); setAuth(null); setError('') } }, '手动配置'))
+    const qrBody = h('div', { className: 'qqConnect' },
+      h('div', { className: 'qqsTitle' }, auth ? '使用 QQ 扫码授权' : '连接 QQ Bot'),
+      h('div', { className: 'qqMuted' }, '使用手机 QQ 扫描官方 Bot 授权二维码。扫码和凭据解密都在 DSH Host 侧完成。'),
+      auth && h('div', { className: 'qqQr' }, h('img', { src: auth.qrDataUrl, alt: 'QQ 授权二维码' })),
+      h(Button, { variant: 'primary', disabled: busy, onClick: () => void startAuth() }, auth ? '重新生成二维码' : '生成二维码'))
+    const manualBody = h('div', { className: 'qqConnect qqManualConnect' },
+      h('div', { className: 'qqsTitle' }, '手动配置 QQ Bot'),
+      h('div', { className: 'qqMuted' }, '填写 QQ 开放平台创建的 AppID 和 AppSecret。密钥只提交到 DSH Host，不会显示在会话或日志中。'),
+      h(Input, { value: manualAppId, placeholder: 'AppID', onChange: (event: import('react').ChangeEvent<HTMLInputElement>) => setManualAppId(event.target.value) }),
+      h(Input, { type: 'password', value: manualAppSecret, placeholder: 'AppSecret', onChange: (event: import('react').ChangeEvent<HTMLInputElement>) => setManualAppSecret(event.target.value) }),
+      h('label', { className: 'qqCheckRow' }, h('input', { type: 'checkbox', checked: manualSandbox, onChange: (event: import('react').ChangeEvent<HTMLInputElement>) => setManualSandbox(event.target.checked) }), h('span', null, '使用沙箱环境')),
+      h(Button, { variant: 'primary', disabled: busy || !manualAppId.trim() || !manualAppSecret.trim(), onClick: () => void connectManual() }, busy ? '验证并连接中…' : '验证并连接'))
+    return h('div', { className: 'qqs' }, head, error && h('div', { className: 'qqError' }, error), modeButtons, connectionMode === 'qr' ? qrBody : manualBody)
+  }
   if (!settings) return h('div', { className: 'qqs' }, head, h('div', { className: 'qqMuted' }, '正在读取设置…'))
 
   const receiveButtons = h('div', { className: 'qqChoiceButtons' },
@@ -171,7 +201,7 @@ export function QQSettings({ rpc }: { rpc: Rpc }) {
     h('div', { className: 'qqSetting' },
       h('div', null,
         h('div', { className: 'qqSettingTitle' }, '启用记忆系统'),
-        h('div', { className: 'qqSettingHelp' }, '记忆会注入每轮 Agent 上下文，并在空闲时整理近期消息；这可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')),
+        h('div', { className: 'qqSettingHelp' }, '记忆会在新 Session、上下文 TTL 过期、记忆变化或 Session 压缩后刷新，不会每轮重复注入完整上下文；后台会在空闲时整理近期消息。启用记忆可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')),
       h('div', { className: 'qqControl' }, h(Button, { size: 'sm', variant: settings.memoryEnabled ? 'primary' : 'outline', onClick: () => void patch({ memoryEnabled: !settings.memoryEnabled }) }, settings.memoryEnabled ? '已启用' : '已关闭'))))
   const ownerSetting = !settings.groupMembersCanUseTools
     ? h('div', { className: 'qqSetting' },

package/docs/ARCHITECTURE.en.md

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

package/docs/ARCHITECTURE.md

@@ -47,14 +47,9 @@ QQ私聊 · <昵称>
 
 Client 不再注册 `sidebar.footer.action` 会话选择器。QQ Session 直接由 DSH 自己的 Session/Workspace Browser 展示和打开。
 
-DSH 用 `turn/start` 判断一个 Session 是否仍为 blank。只有静默记录的新 QQ peer 没有正常 Agent turn，因此插件创建 Session 后提交一次 `qq-chat-bootstrap` wake，并在 `agent/pre-step` 立即 reject。结果是：
-
-- 有 durable turn boundary；
-- Session 能进入 DSH 正常列表；
-- 没有 model step；
-- 不调用 LLM；
-- 不发送 QQ 消息；
-- bootstrap 不进入模型 history。
+QQChat 不再提交内部 bootstrap wake。新建的静默 Session 保持 DSH 原生 blank 状态，因此可以直接使用 DSH 的 Agent Preset 选择器；第一条真正触发 Agent 的 QQ 消息才会创建正常 turn boundary。
+
+插件配置中的 `agentPreset` 只用于新 Session。Session 被 DSH Web 选择过 preset 后，DSH 会写入 `agent-preset/selected` 事件；QQChat 恢复 Session 时读取该事件，优先恢复 Session 最近一次选择的 preset。
 
 ## Settings 边界
 

package/docs/MEDIA_AND_QUOTES.md

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

package/docs/SECURITY.md

@@ -6,7 +6,7 @@ QQChat 同时接触 QQ 凭据、用户身份、群消息和 DSH Session。安全
 
 ## 凭据边界
 
-- AppSecret、QQ Token、扫码 AES 临时 key 只存在 Host。
+- AppSecret、QQ Token、扫码 AES 临时 key 只存在 Host；手动连接表单只通过 loopback RPC 提交 AppSecret，验证失败时不保存新凭据。
 - 浏览器只通过受限 RPC 获取状态和已经脱敏的展示数据。
 - 凭据不写入 URL、日志、前端状态、测试 fixture 或 Git。
 - SQLite 数据目录默认位于 `$DSH_HOME/plugins/dsh-qqchat/`，应由本地用户权限保护。

package/docs/STREAMING.md

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

package/lib/client.js

@@ -29,6 +29,10 @@ function QQSettings({ rpc }) {
     const [members, setMembers] = (0, shared_cjs_1.useState)(() => qqSettingsCache?.members || []);
     const [loading, setLoading] = (0, shared_cjs_1.useState)(() => qqSettingsCache === undefined);
     const [auth, setAuth] = (0, shared_cjs_1.useState)(null);
+    const [connectionMode, setConnectionMode] = (0, shared_cjs_1.useState)('qr');
+    const [manualAppId, setManualAppId] = (0, shared_cjs_1.useState)('');
+    const [manualAppSecret, setManualAppSecret] = (0, shared_cjs_1.useState)('');
+    const [manualSandbox, setManualSandbox] = (0, shared_cjs_1.useState)(false);
     const [logs, setLogs] = (0, shared_cjs_1.useState)(null);
     const [busy, setBusy] = (0, shared_cjs_1.useState)(false);
     const [error, setError] = (0, shared_cjs_1.useState)('');
@@ -125,6 +129,21 @@ function QQSettings({ rpc }) {
             setBusy(false);
         }
     };
+    const connectManual = async () => {
+        setBusy(true);
+        try {
+            await (0, shared_cjs_1.call)(rpc, 'account/manual-connect', { appId: manualAppId, appSecret: manualAppSecret, sandbox: manualSandbox });
+            setManualAppSecret('');
+            await refresh();
+            setError('');
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
     const disconnect = async () => {
         if (!account)
             return;
@@ -184,8 +203,12 @@ function QQSettings({ rpc }) {
     const head = (0, shared_cjs_1.h)('div', { className: 'qqsHead' }, (0, shared_cjs_1.h)('div', null, (0, shared_cjs_1.h)('div', { className: 'qqsTitle' }, 'QQ Chat'), (0, shared_cjs_1.h)('div', { className: 'qqMuted' }, 'QQ Bot 接收、兼容与权限设置')), (0, shared_cjs_1.h)('div', { className: 'qqStatus' }, loading ? '加载中…' : account ? (account.gatewayStatus === 'online' ? '已连接' : '已授权') : '未连接', account && (0, shared_cjs_1.h)(shared_cjs_1.Button, { size: 'sm', variant: 'outline', disabled: busy, onClick: () => void disconnect() }, '取消连接')));
     if (loading)
         return (0, shared_cjs_1.h)('div', { className: 'qqs' }, head, (0, shared_cjs_1.h)('div', { className: 'qqMuted' }, '正在读取 QQ Chat 设置…'));
-    if (!account)
-        return (0, shared_cjs_1.h)('div', { className: 'qqs' }, head, error && (0, shared_cjs_1.h)('div', { className: 'qqError' }, error), (0, shared_cjs_1.h)('div', { className: 'qqConnect' }, (0, shared_cjs_1.h)('div', { className: 'qqsTitle' }, auth ? '使用 QQ 扫码授权' : '连接 QQ Bot'), (0, shared_cjs_1.h)('div', { className: 'qqMuted' }, '扫码和凭据解密都在 DSH Host 侧完成。'), auth && (0, shared_cjs_1.h)('div', { className: 'qqQr' }, (0, shared_cjs_1.h)('img', { src: auth.qrDataUrl, alt: 'QQ 授权二维码' })), (0, shared_cjs_1.h)(shared_cjs_1.Button, { variant: 'primary', disabled: busy, onClick: () => void startAuth() }, auth ? '重新生成二维码' : '扫码连接')));
+    if (!account) {
+        const modeButtons = (0, shared_cjs_1.h)('div', { className: 'qqChoiceButtons' }, (0, shared_cjs_1.h)(shared_cjs_1.Button, { size: 'sm', variant: connectionMode === 'qr' ? 'primary' : 'outline', onClick: () => { setConnectionMode('qr'); setError(''); } }, '扫码连接'), (0, shared_cjs_1.h)(shared_cjs_1.Button, { size: 'sm', variant: connectionMode === 'manual' ? 'primary' : 'outline', onClick: () => { setConnectionMode('manual'); setAuth(null); setError(''); } }, '手动配置'));
+        const qrBody = (0, shared_cjs_1.h)('div', { className: 'qqConnect' }, (0, shared_cjs_1.h)('div', { className: 'qqsTitle' }, auth ? '使用 QQ 扫码授权' : '连接 QQ Bot'), (0, shared_cjs_1.h)('div', { className: 'qqMuted' }, '使用手机 QQ 扫描官方 Bot 授权二维码。扫码和凭据解密都在 DSH Host 侧完成。'), auth && (0, shared_cjs_1.h)('div', { className: 'qqQr' }, (0, shared_cjs_1.h)('img', { src: auth.qrDataUrl, alt: 'QQ 授权二维码' })), (0, shared_cjs_1.h)(shared_cjs_1.Button, { variant: 'primary', disabled: busy, onClick: () => void startAuth() }, auth ? '重新生成二维码' : '生成二维码'));
+        const manualBody = (0, shared_cjs_1.h)('div', { className: 'qqConnect qqManualConnect' }, (0, shared_cjs_1.h)('div', { className: 'qqsTitle' }, '手动配置 QQ Bot'), (0, shared_cjs_1.h)('div', { className: 'qqMuted' }, '填写 QQ 开放平台创建的 AppID 和 AppSecret。密钥只提交到 DSH Host，不会显示在会话或日志中。'), (0, shared_cjs_1.h)(shared_cjs_1.Input, { value: manualAppId, placeholder: 'AppID', onChange: (event) => setManualAppId(event.target.value) }), (0, shared_cjs_1.h)(shared_cjs_1.Input, { type: 'password', value: manualAppSecret, placeholder: 'AppSecret', onChange: (event) => setManualAppSecret(event.target.value) }), (0, shared_cjs_1.h)('label', { className: 'qqCheckRow' }, (0, shared_cjs_1.h)('input', { type: 'checkbox', checked: manualSandbox, onChange: (event) => setManualSandbox(event.target.checked) }), (0, shared_cjs_1.h)('span', null, '使用沙箱环境')), (0, shared_cjs_1.h)(shared_cjs_1.Button, { variant: 'primary', disabled: busy || !manualAppId.trim() || !manualAppSecret.trim(), onClick: () => void connectManual() }, busy ? '验证并连接中…' : '验证并连接'));
+        return (0, shared_cjs_1.h)('div', { className: 'qqs' }, head, error && (0, shared_cjs_1.h)('div', { className: 'qqError' }, error), modeButtons, connectionMode === 'qr' ? qrBody : manualBody);
+    }
     if (!settings)
         return (0, shared_cjs_1.h)('div', { className: 'qqs' }, head, (0, shared_cjs_1.h)('div', { className: 'qqMuted' }, '正在读取设置…'));
     const receiveButtons = (0, shared_cjs_1.h)('div', { className: 'qqChoiceButtons' }, ...['auto', 'mention', 'silent'].map(mode => (0, shared_cjs_1.h)(shared_cjs_1.Button, {
@@ -204,7 +227,7 @@ function QQSettings({ rpc }) {
         : settings.directStreamingEnabled
             ? '使用 QQ 官方流式接口逐步更新私聊回复；部分 QQ 客户端可能看不到流式效果。'
             : '使用普通一次性消息发送，兼容性更好。')))));
-    const memoryGroup = (0, shared_cjs_1.h)('div', { className: 'qqSettingsGroup' }, (0, shared_cjs_1.h)('h3', null, '记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSetting' }, (0, shared_cjs_1.h)('div', null, (0, shared_cjs_1.h)('div', { className: 'qqSettingTitle' }, '启用记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSettingHelp' }, '记忆会注入每轮 Agent 上下文，并在空闲时整理近期消息；这可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')), (0, shared_cjs_1.h)('div', { className: 'qqControl' }, (0, shared_cjs_1.h)(shared_cjs_1.Button, { size: 'sm', variant: settings.memoryEnabled ? 'primary' : 'outline', onClick: () => void patch({ memoryEnabled: !settings.memoryEnabled }) }, settings.memoryEnabled ? '已启用' : '已关闭'))));
+    const memoryGroup = (0, shared_cjs_1.h)('div', { className: 'qqSettingsGroup' }, (0, shared_cjs_1.h)('h3', null, '记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSetting' }, (0, shared_cjs_1.h)('div', null, (0, shared_cjs_1.h)('div', { className: 'qqSettingTitle' }, '启用记忆系统'), (0, shared_cjs_1.h)('div', { className: 'qqSettingHelp' }, '记忆会在新 Session、上下文 TTL 过期、记忆变化或 Session 压缩后刷新，不会每轮重复注入完整上下文；后台会在空闲时整理近期消息。启用记忆可能降低上下文缓存命中率并增加输入 token。关闭后停止记忆注入和后台整理，但不会删除已有记忆。')), (0, shared_cjs_1.h)('div', { className: 'qqControl' }, (0, shared_cjs_1.h)(shared_cjs_1.Button, { size: 'sm', variant: settings.memoryEnabled ? 'primary' : 'outline', onClick: () => void patch({ memoryEnabled: !settings.memoryEnabled }) }, settings.memoryEnabled ? '已启用' : '已关闭'))));
     const ownerSetting = !settings.groupMembersCanUseTools
         ? (0, shared_cjs_1.h)('div', { className: 'qqSetting' }, (0, shared_cjs_1.h)('div', null, (0, shared_cjs_1.h)('div', { className: 'qqSettingTitle' }, 'Owner stable ID'), (0, shared_cjs_1.h)('div', { className: 'qqSettingHelp' }, '使用 stable sender ID，不根据昵称判断。')), (0, shared_cjs_1.h)('div', { className: 'qqControl' }, (0, shared_cjs_1.h)(shared_cjs_1.Input, {
             value: settings.ownerUserId,

package/lib/gateway/api.d.ts

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

package/lib/gateway/api.js

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

package/lib/gateway/gateway.js

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