dsh-qq-tools 0.7.0 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 给 DSH（DeepSeek Harness）里的大肥鱼会话用的 QQ 群/私聊工具，走 OneBot 11 HTTP + WebSocket。系统表情在 SnowLuma / NapCat 上都能发；收藏表情用 SnowLuma 的自定义表情扩展接口，和 QQ 客户端里的收藏夹是同一份数据。
 
-8 个工具各自是一个独立的 cordis 组件，在 DSH 插件页的「包含的组件」里可以逐个开关：
+8 个工具各自是一个独立的 cordis 组件，外加一个负责选择挂载会话的设置组件，在 DSH 插件页的「包含的组件」里可以逐个开关：
 
 | 组件 | 工具 | 说明 |
 | --- | --- | --- |
@@ -14,15 +14,18 @@
 | 收藏表情 | `qq_list_faces` / `qq_favorite_face` | 看/管理 QQ 账号收藏夹（SnowLuma）：收藏图片、取消收藏、改备注、移到最前 |
 | 私聊 | `qq_list_friends` / `qq_get_private_history` / `qq_send_private_message` | 好友列表、私聊记录、发私聊消息；同时负责私聊消息唤醒 |
 | 戳一戳 | `qq_send_poke` | 戳人；同时负责接收戳一戳事件 |
+| 挂载会话 | — | 插件页里的「配置」页面：下拉选择 QQ 消息唤醒哪个 DSH 会话 |
 
-关掉「发群消息」会同时停掉 @ 提醒轮询，关掉「私聊」会同时停掉私聊消息唤醒，关掉「戳一戳」会同时停掉戳一戳通知；三个只读工具互不影响。
+关掉「发群消息」会同时停掉 @ 提醒轮询，关掉「私聊」会同时停掉私聊消息唤醒，关掉「戳一戳」会同时停掉戳一戳通知；三个只读工具互不影响。关掉「挂载会话」只会让配置页面不可用，已经写进配置的 `targetSession` 仍然生效。
 
 ## 目录结构
 
 ```
-cordis.patch.yml                 8 个组件行
+cordis.patch.yml                 9 个组件行
 lib/shared.js                    共享核心：配置、OneBot、挂载、@ 轮询、私聊唤醒、戳一戳、表情、观察窗
-lib/index.js                     兼容入口：一个插件挂全部工具（bundle 不使用）
+lib/client.js                    浏览器半侧：插件页里的挂载会话下拉框
+lib/index.js                     包根 carrier（承载浏览器半侧和挂载会话接口），也是旧的全量入口
+locale/                          包根行在插件页显示的标题和说明
 tools/qq-list-groups/            组件入口 + locale
 tools/qq-get-group-history/
 tools/qq-get-group-members/
@@ -33,7 +36,19 @@ tools/qq-private-chat/
 tools/qq-send-poke/
 ```
 
-每个 `tools/<组件>/index.js` 只做一件事：把自己的工具挂到目标会话。`locale/{en,zh}.json` 提供插件页显示的标题和说明。
+「挂载会话」用的是包根行（模块名 `dsh-qq-tools`，所以插件卡片名仍是 `dsh-qq-tools`）：DSH 只从包根发现 `dsh.client`，子路径行不会扫描；`config.carrier: true` 让它只承载设置接口，不会重复挂一遍工具。
+
+每个 `tools/<组件>/index.js` 只做一件事：把自己的工具挂到目标会话。`locale/{en,zh}.json` 提供插件页显示的标题和说明；左侧栏入口和插件行配置页在 `lib/client.js` 里注册。
+
+## 选择挂载会话
+
+左侧栏的「挂载会话」入口（也可以在「插件 → dsh-qq-tools → 挂载会话 → 配置」里打开）会列出当前 DSH 里的会话（标题 + 短 ID + 运行状态）。选中后保存，配置写回 `~/.dsh/qq-tools-config.json` 的 `targetSession`，各组件在 3 秒内重新挂到这个会话。
+
+- 归档会话和子会话不会出现在列表里；如果当前目标后来被归档，列表会把它标成「当前目标（已归档）」。
+- 工具只注册在选中的会话上，其他会话看不到 QQ 工具，也不会被 QQ 消息唤醒。
+- 选「不挂载」或留空会卸下所有工具并停止唤醒。
+- 保存时不校验会话是否存活：会话暂时关掉不会把配置清掉，等它重新打开后会自动挂上。
+- 这个页面依赖「挂载会话」组件；关掉该组件后接口不可用，但已保存的 `targetSession` 仍然生效，也可以直接改配置文件。
 
 ## 配置
 
@@ -59,7 +74,7 @@ tools/qq-send-poke/
 ```
 
 - `napCat` 是 OneBot 11 HTTP 地址（SnowLuma 默认 `http://127.0.0.1:3000`，NapCat 也一样）；`wsUrl` 是 WebSocket 事件地址（默认 `ws://127.0.0.1:3001`）。
-- `targetSession` 是目标会话 ID；留空时工具不会挂到任何会话。
+- `targetSession` 是目标会话 ID；可以在插件页「挂载会话 → 配置」里下拉选择，也可以直接改这个文件；留空时工具不会挂到任何会话。
 - `groups` 是允许看/发的群；空数组表示不限制。
 - `mentionEnabled` / `pokeEnabled` / `privateEnabled` 分别是 @ 轮询、戳一戳事件、私聊唤醒的总闸，对应组件关掉时它们也不会运行。
 - `privateUsers` 是允许唤醒和私聊工具的 QQ 白名单；空数组表示不限制。非空时，不在列表里的私聊消息不会唤醒，`qq_list_friends` 也不会列出他们。
@@ -84,7 +99,7 @@ tools/qq-send-poke/
 
 私聊和群聊在程序里是分开的两条路径：群聊靠轮询 @，私聊靠 WebSocket 的 `message_type=private` 事件。私聊没有观察窗，每收到一条私聊消息都会直接唤醒目标会话。
 
-- 唤醒提示里会带发送者昵称、QQ 号、`message_id` 和文字；如果消息里有图片，也会把图片一起给模型看。
+- 唤醒提示里会带发送者昵称、QQ 号、`message_id` 和文字；如果消息里有图片，也会把图片一起给模型看（GIF 会拆成首/中/尾最多 3 帧，和群聊记录的处理一致）。
 - 模型用 `qq_get_private_history` 看和对方的最近记录，用 `qq_send_private_message` 回文字，用 `qq_send_face` 回表情。
 - `qq_list_friends` 列好友，可以按昵称、备注或 QQ 号搜；`privateUsers` 非空时只列白名单里的好友。
 - `qq_get_private_history` 的消息带 `#message_id`，可以传给 `qq_send_private_message` / `qq_send_face` 的 `reply_to` 做引用回复。
@@ -102,12 +117,20 @@ dsh plugin --profile <profile> add github:cyhddyx/dsh-qq-tools
 
 本插件是纯 JavaScript，没有构建步骤，所以不需要 `prepare` 脚本，也不需要给 pnpm 加 `allowBuilds` 授权。安装完成后重启 DSH，插件页里应该能看到 8 个组件，每个带开关。
 
-### 从 npm 安装（发布后可用）
+### 从 npm 安装（推荐）
+
+已发布到 npm，装最新版：
 
 ```sh
 dsh plugin --profile <profile> add dsh-qq-tools
 ```
 
+需要固定版本时：
+
+```sh
+dsh plugin --profile <profile> add dsh-qq-tools@0.8.0
+```
+
 ### 本地开发 / 自己改代码
 
 ```sh
@@ -118,7 +141,7 @@ dsh plugin --profile <profile> add link:/path/to/dsh-qq-tools
 
 ```sh
 pnpm pack
-dsh plugin --profile <profile> add ./dsh-qq-tools-0.7.0.tgz
+dsh plugin --profile <profile> add ./dsh-qq-tools-0.8.0.tgz
 ```
 
 `dsh plugin` 会在安装后自动把这个包追加进 profile 的 `dsh.profile.bundles`，不用手改 `package.json`。卸载用：
@@ -132,8 +155,8 @@ dsh plugin --profile <profile> remove dsh-qq-tools
 - DSH 0.2.x（cordis 插件体系）
 - Node.js 22+（内置 `fetch` / `WebSocket`）
 - SnowLuma 提供 OneBot 11 HTTP 接口和 WebSocket 事件（收藏表情需要 SnowLuma；系统表情 NapCat 也能发）
-- 可选：`sharp`（GIF 帧拆分；没有也能用，GIF 会按静图处理）
+- 可选：`sharp`（GIF 帧拆分）。会自动使用插件自己装的、`SHARP_PATH` 指定的，或 DSH 宿主自带的 sharp；都找不到时 GIF 按静图处理
 
 ---
 
-版本：0.7.0
+版本：0.8.0

package/cordis.patch.yml

@@ -1,10 +1,11 @@
-# DSH 大肥鱼 QQ 群/私聊工具：8 个工具各是一个独立组件，插件页里可以逐个开关
+# DSH 大肥鱼 QQ 群/私聊工具：9 个组件，插件页里可以逐个开关
 #   · 列出 QQ 群 / 看群聊天记录 / 看群成员 —— 只读工具
 #   · 发群消息 —— 同时负责 @ 提醒与群后续轮询
 #   · 发表情 —— 在群里或私聊里发系统表情或 QQ 收藏夹里的自定义表情
 #   · 收藏表情 —— QQ 收藏夹（SnowLuma）：qq_list_faces + qq_favorite_face
 #   · 私聊 —— 好友列表 / 私聊记录 / 发私聊消息，同时负责私聊消息唤醒
 #   · 戳一戳 —— 同时负责接收戳一戳事件
+#   · 挂载会话 —— 插件页里的「配置」页面，选择 QQ 消息唤醒哪个 DSH 会话
 - insert:
     - id: qq-tools-list-groups
       name: 'dsh-qq-tools/tools/qq-list-groups'
@@ -22,3 +23,8 @@
       name: 'dsh-qq-tools/tools/qq-private-chat'
     - id: qq-tools-send-poke
       name: 'dsh-qq-tools/tools/qq-send-poke'
+    # 包根行：DSH 只从包根发现 dsh.client，浏览器半侧和挂载会话接口都挂在这里。
+    - id: qq-tools-root
+      name: 'dsh-qq-tools'
+      config:
+        carrier: true

package/lib/client.js

@@ -0,0 +1,328 @@
+// dsh-qq-tools 的浏览器半侧：左侧栏「挂载会话」入口 + 插件行配置页。
+// 会话列表来自 slot 自带的 useSessions，归档集合来自 useWorkspaces；
+// 读写走宿主半侧的 /api/dsh-qq-tools/target-session，最终仍然落在
+// ~/.dsh/qq-tools-config.json 的 targetSession 字段上。
+window.__ModuleLoader__.load({
+  id: 'dsh-qq-tools',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const react = require('react')
+    const h = react.createElement
+
+    const NS = 'qq-tools'
+    const API = '/api/dsh-qq-tools/target-session'
+    const SLOT_KEY = 'dsh-qq-tools#qq-tools-root'
+    const PANEL_ID = 'qq-tools-target-session'
+    const PANEL_ORDER = 50
+    const EMPTY_IDS = []
+
+    const zh = {
+      summary: 'QQ 消息挂载会话',
+      sidebarLabel: '挂载会话',
+      panelTitle: '挂载会话',
+      description: '只有这里选中的 DSH 会话会收到 QQ 群 @、群后续、私聊和戳一戳；QQ 工具也只挂在这个会话上。保存后约 3 秒生效。',
+      none: '不挂载（关闭 QQ 唤醒）',
+      untitled: '未命名会话',
+      running: '（运行中）',
+      missing: '当前目标（会话未运行）',
+      archived: '当前目标（已归档）',
+      refresh: '刷新',
+      save: '保存',
+      saving: '保存中…',
+      saved: '已保存，约 3 秒内生效',
+      loading: '读取中…',
+      failed: '操作失败：',
+      current: '当前挂载：',
+      empty: '当前没有挂载任何会话。',
+      unavailable: '接口不可用。请先在插件页启用「挂载会话」组件。',
+    }
+
+    const en = {
+      summary: 'QQ target session',
+      sidebarLabel: 'Target session',
+      panelTitle: 'Target session',
+      description: 'Only the selected DSH session receives QQ mentions, follow-ups, private messages and pokes; QQ tools are mounted there too. Changes apply within about 3 seconds.',
+      none: 'Do not mount (disable QQ wake-ups)',
+      untitled: 'Untitled session',
+      running: ' (running)',
+      missing: 'Current target (not running)',
+      archived: 'Current target (archived)',
+      refresh: 'Refresh',
+      save: 'Save',
+      saving: 'Saving…',
+      saved: 'Saved; applies within about 3 seconds',
+      loading: 'Loading…',
+      failed: 'Request failed: ',
+      current: 'Mounted to: ',
+      empty: 'No session is mounted.',
+      unavailable: 'Endpoint unavailable. Enable the "Target session" component on the plugin page first.',
+    }
+
+    const inject = ['slots', 'locale']
+
+    function shortId(id) {
+      const s = String(id || '')
+      return s.length > 12 ? s.slice(0, 8) + '…' : s
+    }
+
+    // 宿主在插件行未启用时返回 404/HTML；先把文本读出来再解析，避免 r.json() 直接抛。
+    function readJsonResponse(response) {
+      return response.text().then((text) => {
+        let body = {}
+        try { body = text ? JSON.parse(text) : {} } catch (error) {}
+        return { ok: response.ok, body }
+      })
+    }
+
+    function TargetSessionCard(props) {
+      const t = props.t
+      const list = props.useSessions((state) => state)
+      const useWorkspaces = props.useWorkspaces || (() => EMPTY_IDS)
+      const archivedSessionIds = useWorkspaces((state) => (state && state.archivedSessionIds) || EMPTY_IDS) || EMPTY_IDS
+      const archived = react.useMemo(() => new Set(archivedSessionIds), [archivedSessionIds])
+      const [current, setCurrent] = react.useState('')
+      const [selected, setSelected] = react.useState('')
+      const [liveIds, setLiveIds] = react.useState([])
+      const [phase, setPhase] = react.useState('loading')
+      const [detail, setDetail] = react.useState('')
+      const [loaded, setLoaded] = react.useState(false)
+
+      const load = react.useCallback(() => {
+        setPhase('loading')
+        setDetail('')
+        fetch(API, { headers: { accept: 'application/json' } })
+          .then(readJsonResponse)
+          .then(({ ok, body }) => {
+            if (!ok || !body || body.ok !== true) {
+              throw new Error((body && body.error) || t('unavailable'))
+            }
+            const value = typeof body.targetSession === 'string' ? body.targetSession : ''
+            setCurrent(value)
+            setSelected(value)
+            setLiveIds(Array.isArray(body.liveSessionIds) ? body.liveSessionIds : [])
+            setLoaded(true)
+            setPhase('ready')
+          })
+          .catch((error) => {
+            setDetail(String((error && error.message) || error))
+            setPhase('error')
+          })
+      }, [t])
+
+      react.useEffect(() => {
+        load()
+      }, [load])
+
+      const save = react.useCallback(() => {
+        setPhase('saving')
+        setDetail('')
+        fetch(API, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json' },
+          body: JSON.stringify({ targetSession: selected }),
+        })
+          .then(readJsonResponse)
+          .then(({ ok, body }) => {
+            if (!ok || !body || body.ok !== true) {
+              throw new Error((body && body.error) || 'save failed')
+            }
+            const value = typeof body.targetSession === 'string' ? body.targetSession : ''
+            setCurrent(value)
+            setSelected(value)
+            setPhase('saved')
+          })
+          .catch((error) => {
+            setDetail(String((error && error.message) || error))
+            setPhase('error')
+          })
+      }, [selected])
+
+      const sessions = react.useMemo(() => {
+        const ids = Array.isArray(list && list.ids) ? list.ids : []
+        const byId = (list && list.byId) || {}
+        return ids.map((id) => byId[id]).filter(Boolean)
+      }, [list])
+
+      const options = [h('option', { key: '__none', value: '' }, t('none'))]
+      let selectedInList = false
+      for (const session of sessions) {
+        if (!session || !session.id) continue
+        if (session.origin === 'subagent') continue
+        if (archived.has(session.id)) continue
+        if (session.id === selected) selectedInList = true
+        const title = String(session.title || '').trim() || t('untitled')
+        const running = session.running === true || liveIds.indexOf(session.id) >= 0
+        options.push(h(
+          'option',
+          { key: session.id, value: session.id },
+          title + ' · ' + shortId(session.id) + (running ? t('running') : ''),
+        ))
+      }
+      if (selected && !selectedInList) {
+        options.push(h(
+          'option',
+          { key: '__current', value: selected },
+          (archived.has(selected) ? t('archived') : t('missing')) + ' · ' + shortId(selected),
+        ))
+      }
+
+      if (props.view === 'summary') {
+        return h('span', null, current ? t('current') + shortId(current) : t('empty'))
+      }
+
+      let statusText = ''
+      let statusColor = 'var(--dsw-alias-label-tertiary)'
+      if (phase === 'loading') statusText = t('loading')
+      else if (phase === 'saving') statusText = t('saving')
+      else if (phase === 'saved') {
+        statusText = t('saved')
+        statusColor = 'var(--dsw-alias-state-success-primary, #2f9e44)'
+      } else if (phase === 'error') {
+        statusText = t('failed') + (detail || t('unavailable'))
+        statusColor = 'var(--dsw-alias-state-error-primary, #d64545)'
+      } else {
+        statusText = current ? t('current') + shortId(current) : t('empty')
+      }
+
+      const disabled = !loaded || phase === 'saving'
+      return h('div', { style: { display: 'flex', flexDirection: 'column', gap: 10 } }, [
+        h('p', {
+          key: 'desc',
+          style: { margin: 0, fontSize: 13, lineHeight: '20px', color: 'var(--dsw-alias-label-secondary)' },
+        }, t('description')),
+        h('div', { key: 'row', style: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' } }, [
+          h('select', {
+            key: 'select',
+            value: selected,
+            disabled,
+            onChange: (event) => {
+              setSelected(event.target.value)
+              if (phase === 'saved' || phase === 'error') setPhase('ready')
+            },
+            style: {
+              minWidth: 280,
+              maxWidth: '100%',
+              height: 36,
+              padding: '0 10px',
+              borderRadius: 8,
+              border: '0.5px solid var(--dsw-alias-border-l4)',
+              background: 'var(--dsw-alias-bg-layer-3)',
+              color: 'var(--dsw-alias-label-primary)',
+              font: 'inherit',
+              fontSize: 13,
+              outline: 'none',
+            },
+          }, options),
+          h('button', {
+            key: 'refresh',
+            type: 'button',
+            disabled: phase === 'loading' || phase === 'saving',
+            onClick: load,
+            style: {
+              height: 36,
+              padding: '0 14px',
+              borderRadius: 8,
+              border: '0.5px solid var(--dsw-alias-border-l4)',
+              background: 'var(--dsw-alias-bg-layer-3)',
+              color: 'var(--dsw-alias-label-primary)',
+              font: 'inherit',
+              fontSize: 13,
+              cursor: 'pointer',
+            },
+          }, t('refresh')),
+          h('button', {
+            key: 'save',
+            type: 'button',
+            disabled,
+            onClick: save,
+            style: {
+              height: 36,
+              padding: '0 16px',
+              borderRadius: 8,
+              border: 'none',
+              background: 'var(--dsw-alias-state-business-primary, #4d6bfe)',
+              color: '#fff',
+              font: 'inherit',
+              fontSize: 13,
+              cursor: disabled ? 'default' : 'pointer',
+              opacity: disabled ? 0.6 : 1,
+            },
+          }, phase === 'saving' ? t('saving') : t('save')),
+        ]),
+        h('p', {
+          key: 'status',
+          style: { margin: 0, fontSize: 12, lineHeight: '18px', color: statusColor },
+        }, statusText),
+      ])
+    }
+
+    function TargetSessionIcon(props) {
+      const size = Number(props && props.size) || 16
+      return h('svg', {
+        viewBox: '0 0 16 16',
+        width: size,
+        height: size,
+        fill: 'none',
+        stroke: 'currentColor',
+        strokeWidth: 1.5,
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+        'aria-hidden': 'true',
+        'data-dsh-panel-entry': PANEL_ID,
+      }, [
+        h('path', {
+          key: 'bubble',
+          d: 'M2.5 2.75h9a1.5 1.5 0 0 1 1.5 1.5v3.5a1.5 1.5 0 0 1-1.5 1.5H6.75L4 12.25V9.25H2.5a1.5 1.5 0 0 1-1.5-1.5v-3.5a1.5 1.5 0 0 1 1.5-1.5Z',
+        }),
+        h('path', { key: 'line1', d: 'M4.25 5.5h5.5' }),
+        h('path', { key: 'line2', d: 'M4.25 7.75h3.25' }),
+      ])
+    }
+
+    function TargetSessionPage(props) {
+      const t = props.t
+      return h('div', {
+        style: {
+          height: '100%',
+          boxSizing: 'border-box',
+          overflow: 'auto',
+          padding: '28px 36px 48px',
+          color: 'var(--dsw-alias-label-primary)',
+        },
+      }, [
+        h('h1', {
+          key: 'title',
+          style: { margin: '0 0 18px', fontSize: 20, fontWeight: 600, lineHeight: '28px' },
+        }, t('panelTitle')),
+        h(TargetSessionCard, { key: 'card', ...props, view: 'page' }),
+      ])
+    }
+
+    function apply(ctx) {
+      ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'qq-tools: dictionaries')
+      const t = ctx.locale.bind(NS)
+      ctx.effect(() => ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
+        name: 'sidebar.panellist',
+        id: PANEL_ID,
+        order: PANEL_ORDER,
+        label: () => t('sidebarLabel'),
+      }, TargetSessionIcon)), 'qq-tools: sidebar entry')
+      ctx.effect(() => ctx.slots.inject('main', () => ctx.slots.register({
+        name: 'main',
+        key: PANEL_ID,
+      }, (props) => h(TargetSessionPage, { ...props, t }))), 'qq-tools: main panel')
+      ctx.effect(() => ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
+        name: 'plugins.row.config',
+        key: SLOT_KEY,
+        locale: NS,
+      }, TargetSessionCard)), 'qq-tools: target session page')
+    }
+
+    exports.apply = apply
+    exports.inject = inject
+    return module.exports
+  },
+})

package/lib/index.js

@@ -1,15 +1,21 @@
-// dsh-qq-tools —— 整体插件入口（兼容用）
+// dsh-qq-tools —— 包根入口。
 //
-// 正常的 bundle 入口现在是 cordis.patch.yml 里的 8 个组件行，每个工具一个组件、
-// 各自有开关。这个文件保留成「一个插件挂全部工具」的老入口，方便直接引用
-// `dsh-qq-tools` 的旧配置；DSH 插件页不会用它。
-import { mountAll } from './shared.js'
+// 两用：
+//   · cordis.patch.yml 里的包根行用 config.carrier = true 启动它，只承载
+//     「挂载会话」的 HTTP 接口；浏览器半侧（lib/client.js）也只能从包根行
+//     被发现，子路径行不会被 dsh-client-modules 扫描到。
+//   · 旧配置直接引用 `dsh-qq-tools` 时没有 carrier 标记，仍然挂全部工具。
+import { mountAll, mountTargetSessionRoute } from './shared.js'
 
 export * from './shared.js'
 
 export const name = 'qq-tools'
-export const inject = ['agents', 'timer', 'tools', 'attachments']
+export const inject = ['agents', 'timer', 'tools', 'attachments', 'webServer']
 
-export function apply(ctx) {
+export function apply(ctx, config) {
+  if (config && config.carrier === true) {
+    mountTargetSessionRoute(ctx)
+    return {}
+  }
   return mountAll(ctx)
 }

package/lib/shared.js

@@ -34,7 +34,7 @@
 //
 // 工具本身的开关在 DSH 插件页的组件列表里：关掉某个组件，它就不再注册对应工具。
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, renameSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { randomUUID } from 'node:crypto'
@@ -47,21 +47,36 @@ const DIAG_PATH = join(DSH_HOME, 'qq-tools-diag.log')
 
 
 const requireFromHere = createRequire(import.meta.url)
-let sharp = null
-for (const p of [
-  process.env.SHARP_PATH,
-  '/usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/sharp',
-  '/usr/lib/node_modules/@deepseek-ai/dsh/node_modules/sharp',
-]) {
-  if (!p) continue
-  try {
-    if (existsSync(p)) {
-      sharp = requireFromHere(p)
-      break
-    }
-  } catch (error) {}
+
+// sharp 是可选的，按这个顺序找：SHARP_PATH → 插件自己装的 → 宿主进程能解析到的。
+// DSH 桌面版把 sharp 打在 resources/app.asar/dsh/node_modules 下，CLI 版跟着
+// @deepseek-ai/dsh 的依赖走，所以从宿主的启动入口解析最稳，不用写死安装路径。
+function loadSharp() {
+  const probes = []
+  if (process.env.SHARP_PATH) probes.push(() => requireFromHere(process.env.SHARP_PATH))
+  probes.push(() => requireFromHere('sharp'))
+  if (process.argv[1]) probes.push(() => createRequire(process.argv[1])('sharp'))
+  if (process.resourcesPath) {
+    probes.push(() => createRequire(join(process.resourcesPath, 'app.asar', 'dsh', 'package.json'))('sharp'))
+  }
+  for (const p of [
+    '/usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/sharp',
+    '/usr/lib/node_modules/@deepseek-ai/dsh/node_modules/sharp',
+  ]) {
+    probes.push(() => requireFromHere(p))
+  }
+  for (const probe of probes) {
+    try {
+      const s = probe()
+      if (s) return s
+    } catch (error) {}
+  }
+  return null
 }
 
+const sharp = loadSharp()
+let gifWarned = false
+
 const DEFAULT_GROUPS = []
 const DEFAULT_CFG = {
   napCat: 'http://127.0.0.1:3000',
@@ -122,6 +137,28 @@ function loadCfg() {
   }
 }
 
+// UI 保存挂载会话时只覆盖传进来的字段，其余配置原样保留；先写临时文件再换名，
+// 避免写一半留下坏 JSON 让后面所有工具都退回默认配置。
+export function saveCfg(patch) {
+  ensureCfg()
+  let current = {}
+  try {
+    const raw = JSON.parse(readFileSync(CFG_PATH, 'utf8'))
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) current = raw
+  } catch (error) {}
+  const next = { ...current, ...(patch && typeof patch === 'object' ? patch : {}) }
+  try {
+    mkdirSync(DSH_HOME, { recursive: true })
+    const tmp = CFG_PATH + '.tmp'
+    writeFileSync(tmp, JSON.stringify(next, null, 2), 'utf8')
+    renameSync(tmp, CFG_PATH)
+  } catch (error) {
+    diag('保存配置失败：' + String((error && error.message) || error))
+    throw error
+  }
+  return next
+}
+
 function targetSessionId() {
   const cfg = loadCfg()
   return String(cfg.targetSession || '')
@@ -157,6 +194,103 @@ function findAgent(agents, id) {
   return undefined
 }
 
+
+// ---------- 目标会话 UI 接口（由「挂载会话」组件启动） ----------
+// 浏览器半侧只读写 targetSession：GET 返回当前值和活着的会话，POST 写回配置文件；
+// 其他组件仍然每 3 秒 loadCfg()，所以保存后不需要重启。
+const TARGET_SESSION_ROUTE = '/api/dsh-qq-tools/target-session'
+
+function replyJson(res, status, body) {
+  const text = JSON.stringify(body)
+  try {
+    res.writeHead(status, {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+    })
+    res.end(text)
+  } catch (error) {}
+}
+
+async function readRequestJson(req, max = 64 * 1024) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += buf.length
+    if (size > max) throw new Error('body too large')
+    chunks.push(buf)
+  }
+  if (!chunks.length) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+function sameOriginRequest(req) {
+  const origin = String((req.headers && req.headers.origin) || '')
+  if (!origin) return true
+  try {
+    return new URL(origin).host === String((req.headers && req.headers.host) || '')
+  } catch (error) {
+    return false
+  }
+}
+
+export function mountTargetSessionRoute(ctx) {
+  const webServer = ctx.get('webServer')
+  if (!webServer || typeof webServer.register !== 'function') {
+    diag('挂载会话：宿主没有 webServer，设置页接口不可用')
+    return
+  }
+  ctx.effect(() => {
+    const dispose = webServer.register({
+      kind: 'exact',
+      path: TARGET_SESSION_ROUTE,
+      handler: async (req, res) => {
+        if (!sameOriginRequest(req)) {
+          replyJson(res, 403, { ok: false, error: 'forbidden' })
+          return
+        }
+        const method = String(req.method || 'GET').toUpperCase()
+        if (method === 'GET') {
+          const liveSessionIds = []
+          try {
+            const agents = ctx.get('agents') || ctx.agents
+            for (const agent of (agents && agents.list()) || []) {
+              const sid = sessionIdOf(agent)
+              if (sid) liveSessionIds.push(sid)
+            }
+          } catch (error) {}
+          replyJson(res, 200, { ok: true, targetSession: targetSessionId(), liveSessionIds })
+          return
+        }
+        if (method !== 'POST') {
+          replyJson(res, 405, { ok: false, error: 'method not allowed' })
+          return
+        }
+        let body
+        try {
+          body = await readRequestJson(req)
+        } catch (error) {
+          replyJson(res, 400, { ok: false, error: 'invalid body' })
+          return
+        }
+        const raw = body && typeof body.targetSession === 'string' ? body.targetSession : ''
+        const targetSession = clean(raw).slice(0, 200)
+        try {
+          saveCfg({ targetSession })
+        } catch (error) {
+          replyJson(res, 500, { ok: false, error: 'save failed' })
+          return
+        }
+        diag('目标会话已更新：' + (targetSession || '（不挂载）'))
+        replyJson(res, 200, { ok: true, targetSession })
+      },
+    })
+    return () => {
+      try { dispose() } catch (error) {}
+    }
+  }, 'qq-tools: target session route')
+}
+
 function allowedGroup(groupId, cfg) {
   if (!Array.isArray(cfg.groups) || cfg.groups.length === 0) return true
   return cfg.groups.includes(Number(groupId))
@@ -220,6 +354,14 @@ function segText(segs) {
     .join(''))
 }
 
+// mface（商城表情/表情包）基本都是动图；普通 image 段只能从名字和摘要里猜。
+function animatedSeg(seg) {
+  if (!seg || !seg.data) return false
+  const d = seg.data
+  return seg.type === 'mface' ||
+    /gif|动画/i.test(String(d.summary || '') + ' ' + String(d.file || '') + ' ' + String(d.url || ''))
+}
+
 function fmtTime(sec) {
   const t = Number(sec)
   if (!Number.isFinite(t) || t <= 0) return ''
@@ -427,10 +569,14 @@ export function admitImagesFor(ctx) {
           if (prepared.length >= 6) break
           continue
         }
+        if (!sharp && !gifWarned) {
+          gifWarned = true
+          diag('GIF 帧拆分不可用：没有加载到 sharp，动图会按静图处理')
+        }
       }
       prepared.push({
         caption: String(x.caption || ''),
-        block: { type: 'image', data: bytes.toString('base64'), mediaType: mediaTypeOf(name), name },
+        block: { type: 'image', data: bytes.toString('base64'), mediaType: isGif ? 'image/gif' : mediaTypeOf(name), name },
       })
       if (prepared.length >= 6) break
     }
@@ -491,11 +637,7 @@ export function makeHistoryTool(admitImages) {
             const segs = Array.isArray(m.message) ? m.message : []
             for (const seg of segs) {
               if (!seg || (seg.type !== 'image' && seg.type !== 'mface') || !seg.data) continue
-              const d = seg.data
-              const animated =
-                seg.type === 'mface' ||
-                /gif|动画/i.test(String(d.summary || '') + ' ' + String(d.file || '') + ' ' + String(d.url || ''))
-              picked.push({ m, seg, animated })
+              picked.push({ m, seg, animated: animatedSeg(seg) })
             }
           }
           const anim = picked.filter((x) => x.animated).slice(-2)
@@ -708,10 +850,7 @@ export function makePrivateHistoryTool(admitImages) {
             const segs = Array.isArray(m.message) ? m.message : []
             for (const seg of segs) {
               if (!seg || (seg.type !== 'image' && seg.type !== 'mface') || !seg.data) continue
-              const animated =
-                seg.type === 'mface' ||
-                /gif|动画/i.test(String(seg.data.summary || '') + ' ' + String(seg.data.file || '') + ' ' + String(seg.data.url || ''))
-              picked.push({ m, seg, animated })
+              picked.push({ m, seg, animated: animatedSeg(seg) })
             }
           }
           const anim = picked.filter((x) => x.animated).slice(-2)
@@ -1594,19 +1733,22 @@ async function handlePrivateMessage(ctx, ev, admitImages) {
     '不想回就安静待着；不要用 Markdown，不要提工具，短一点。'
   const content = [{ type: 'text', text: prompt }]
   if (typeof admitImages === 'function') {
-    const picked = []
+    // 和群/私聊记录一样：先保证最近两张动图能进来，剩下的名额给静图。
+    const anim = []
+    const stat = []
     for (const seg of segs) {
       if (!seg || (seg.type !== 'image' && seg.type !== 'mface') || !seg.data) continue
-      picked.push(seg)
-      if (picked.length >= 4) break
+      const item = { seg, animated: animatedSeg(seg) }
+      if (item.animated) anim.push(item)
+      else stat.push(item)
     }
+    const animPick = anim.slice(-2)
+    const picked = [...animPick, ...stat.slice(-(4 - animPick.length))]
     if (picked.length) {
-      const images = await admitImages(picked.map((seg, i) => ({
+      const images = await admitImages(picked.map(({ seg, animated }, i) => ({
         data: seg.data,
         cfg,
-        animated:
-          seg.type === 'mface' ||
-          /gif|动画/i.test(String(seg.data.summary || '') + ' ' + String(seg.data.file || '') + ' ' + String(seg.data.url || '')),
+        animated,
         name: (seg.data && seg.data.file) || `qq-private-${ev.message_id || 'x'}-${i}.jpg`,
         caption: `私聊 ${name} 发的图片（消息 ${ev.message_id || '?'}）`,
       })))

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-qq-tools",
+    "description": "QQ group/private chat tools for DSH: list groups, read history, send messages and faces, manage SnowLuma favorites, private chat, pokes, and target-session selection."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-qq-tools",
+    "description": "给大肥鱼会话用的 QQ 群/私聊工具：列群、看群聊天记录、发群消息、发表情、收藏表情（SnowLuma 收藏夹）、好友/私聊记录、发私聊消息、私聊唤醒、群成员、戳一戳感知/戳回去。"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-qq-tools",
-  "version": "0.7.0",
-  "description": "给大肥鱼会话用的 QQ 群/私聊工具：列群、看群记录、发群消息、发表情、收藏表情（SnowLuma 收藏夹）、好友/私聊记录、发私聊消息、私聊唤醒、群成员、戳一戳感知/戳回去。8 个工具各是一个独立组件，可在插件页逐个开关。",
+  "version": "0.8.0",
+  "description": "给大肥鱼会话用的 QQ 群/私聊工具：列群、看群记录、发群消息、发表情、收藏表情（SnowLuma 收藏夹）、好友/私聊记录、发私聊消息、私聊唤醒、群成员、戳一戳感知/戳回去、挂载会话选择。8 个工具加 1 个设置组件，可在插件页逐个开关。",
   "type": "module",
   "main": "lib/index.js",
   "license": "MIT",
@@ -26,6 +26,7 @@
   "files": [
     "lib",
     "tools",
+    "locale",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
@@ -35,6 +36,7 @@
   },
   "exports": {
     ".": "./lib/index.js",
+    "./client": "./lib/client.js",
     "./tools/qq-list-groups": "./tools/qq-list-groups/index.js",
     "./tools/qq-list-groups/locale/en.json": "./tools/qq-list-groups/locale/en.json",
     "./tools/qq-list-groups/locale/zh.json": "./tools/qq-list-groups/locale/zh.json",
@@ -59,12 +61,22 @@
     "./tools/qq-send-poke": "./tools/qq-send-poke/index.js",
     "./tools/qq-send-poke/locale/en.json": "./tools/qq-send-poke/locale/en.json",
     "./tools/qq-send-poke/locale/zh.json": "./tools/qq-send-poke/locale/zh.json",
+    "./locale/en.json": "./locale/en.json",
+    "./locale/zh.json": "./locale/zh.json",
     "./package.json": "./package.json"
   },
-  "description": "给大肥鱼会话用的 QQ 群/私聊工具：列群、看群记录、发群消息、发表情、收藏表情（SnowLuma 收藏夹）、好友/私聊记录、发私聊消息、私聊唤醒、群成员、戳一戳感知/戳回去。8 个工具各是一个独立组件，可在插件页逐个开关。",
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
+      ],
+      "platform": "web"
     }
   }
 }