dsh-whale-inurqq: A QQ Client Integrated with DeepSeek Harness

DeepSeek Harness 是一个基于插件架构的框架，它的理念是「一切皆插件」。要把 QQ 接入这个框架，需要实现协议层面的通信。dsh-whale-inurqq 是一个 OneBot 11 协议客户端插件。它本身不处理 QQ 登录、签名或加密，这些工作由协议端（如 NapCat）负责。因此，它保持了中立，可以像任何 IM 通道插件一样分发。

下面介绍如何安装、配置以及理解它的运行机制。

核心功能¶

本插件主要解决 QQ 与 DSH 之间的消息路由与会话管理问题：

1. 消息归一化与分类：接收 QQ 消息后，进行归一化处理，并根据内容判断为「闲聊」或「任务」。这一步只决定措辞，不决定后续路由。
2. 常驻对接会话：每个 QQ 会话（群或私聊）对应 DSH 中的一个工作区。该工作区下有一个常驻对接会话，聊天和执行任务都在这个会话中进行，而不是每条消息新建会话。
3. 上下文交班机制：当常驻会话的上下文达到阈值（默认 handoffAtRatio: 0.25）时，会触发交班。旧会话归档，新会话接管，碎片记忆保留。
4. 回合发起者判定：插件通过 source.rpcId 判定当前回合是「插件发起的」还是「用户在 GUI 里发起的」。只有前者才会回传消息到 QQ，后者则完全静默。
5. 非主动推送：插件不会主动推送「正在执行中」的状态。用户需要主动查询时，插件才会通过 qq_alive 和 qq_tasks 查询状态并回答。

前置条件¶

在开始之前，需要准备以下环境：

安装与迁移¶

使用官方命令安装插件：

dsh plugin --profile <你的profile> add dsh-whale-inurqq

安装后重启 DSH 进程。

老用户必读：从 dsh-qq 改名而来¶

本插件原名 dsh-qq，现已改名为 dsh-whale-inurqq。这个改名是无情的字符串替换，运行时数据目录也随之改变：

如果你之前安装过 dsh-qq，建议执行以下迁移步骤以保留数据：

1. 卸载旧插件（它仍以旧包名注册）：

    dsh plugin --profile <你的profile> remove dsh-qq

2. 安装新插件：

    dsh plugin --profile <你的profile> add dsh-whale-inurqq

3. 搬运运行时数据（假设 DSH 默认在 ~/.dsh）：

    # Linux / macOS
    mv ~/.dsh/dsh-qq ~/.dsh/dsh-whale-inurqq
    # Windows PowerShell
    Rename-Item "$env:USERPROFILE\.dsh\dsh-qq" "$env:USERPROFILE\.dsh\dsh-whale-inurqq"

*注意：如果不搬运目录，新插件会视为全新安装，无法读取旧的会话与语料库。*

配置协议端（NapCat）¶

插件默认监听 127.0.0.1:6700。需要在 NapCat 的 config/onebot11.json 中配置一个反向 WebSocket 客户端：

{
  "network": {
    "websocketClients": [
      {
        "name": "dsh-whale-inurqq-reverse",
        "enable": true,
        "url": "ws://127.0.0.1:6700",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "reconnectInterval": 5000,
        "token": "<你的 access token>",
        "heartInterval": 30000
      }
    ]
  }
}

关键配置点：
* url：指向插件监听的地址。
* messagePostFormat：必须设为 array。
* token：需与插件配置中的 QQ_ONEBOT_TOKEN 或 connection.token 一致。

配置项说明¶

插件安装后，会在 DSH 的设置页生成配置项。以下是关键配置的逻辑与风险点。

常驻对接会话（默认开启）¶

conversation.enabled 默认为 true。开启后，QQ 会话与 DSH 工作区共用一个常驻会话。

• 回滚开关：如果将 conversation.enabled 设为 false，插件将回滚到 v2 行为：每条任务新建会话，受 tasks.maxConcurrent 限流，不挂载常驻记忆。
• 交班阈值：handoffAtRatio（默认 0.25）控制上下文窗口使用多少比例时触发交班。此值必须低于宿主压缩的 thresholdRatio，否则压缩会先摘要掉历史。

权限与风险（Scope）¶

QQ 触发的新会话会继承 DSH profile 的默认权限预设。

• 风险提示：如果默认预设是 danger-full-access 且 approval: never，任何能给你的 bot 发消息的人（在 scope 允许范围内）都会获得不受限的文件与 shell 执行能力。
• 公开部署：建议收紧 scope，或使用更严格的默认预设。

任务配置¶

• tasks.workspaceRoot：必填项，指定 QQ 项目目录的父目录。
• ingest.forwardRecords：开启后，合并转发会自动展开入语料。

工作原理与行为细节¶

回传机制的判定逻辑¶

插件通过 source.rpcId 判定回合发起者：
1. 如果 source.rpcId 属于插件发出的 prompt id 集合，说明是插件发起的，照常回传 QQ。
2. 如果不命中（例如用户在 DSH GUI 里自己敲的那句），说明是 GUI 发起的，该回合不回传任何内容。

这一机制防止了用户在电脑前操作 GUI 时，QQ 那边莫名收到回传消息。

进度展示¶

插件不主动推送进度。中间态一律静默。只有当用户在 QQ 上发起查询时，插件才会查询真实状态并如实回答。

交班换新会话¶

当上下文达到阈值时，插件会：
1. 整理成交接束 + 碎片记忆落盘。
2. 归档旧会话。
3. 建立新会话并注入交接文本。
4. 交班期间新来的消息会进入排队（frozenQueue），交班结束后按原顺序补投。

状态查询¶

插件在反向 WebSocket 端口暴露了一个只读状态端点，可用于调试：

curl http://127.0.0.1:6700/dsh-whale-inurqq/status

该接口返回连接状态、事件统计、工作区映射、回传来源判定账目以及任务调度信息。

总结¶

dsh-whale-inurqq 是一个连接 QQ 与 DeepSeek Harness 的 OneBot 11 客户端。它通过常驻会话和上下文交班机制，简化了任务管理的流程，同时通过严格的回合发起者判定和权限控制，保证了交互的安全性。

• 作者：FABAGV
• 许可：MIT
• 仓库：https://github.com/FABAGV/dsh-whale-inurqq
• 目录页：https://www.skillhub.cn/plugins/FABAGV/dsh-whale-inurqq