团队项目第一次作业

黑猫计划：让智能体走进 QQ 日常互动

项目	内容
作业所属课程	构建一个能说会做的智能体（软件工程，广东工业大学计算机学院计科 24 级 56 班）
作业要求	智能体软件项目作业要求
作业目标	将智能体能力嵌入实际软件，完成有真实使用价值的功能，并进行项目展示、需求分析、答辩和博客总结。
团队名称	广工黑猫工坊队
团队成员	3124004085 陈安东；3124004109 杨旭东；3124004096 李家乐；3124004089 陈宇轩；3124004099 李兆希；3124004100 李梓弘
项目名称	黑猫计划（当前接入场景：DSH ↔ QQ）
源码仓库	dsh-wdd-cat-linker
当前演示状态	答辩 PPT 报告本机 Demo 已跑通 QQ 私聊、群聊双向收发及文字、图片和日志链路；当前未提供公网试用地址。

1. 团队展示

1.1 队名与项目规划

队名：广工黑猫工坊队

项目：黑猫计划——通过 Java 中转服务和 DSH 跳板插件，将 QQ 私聊、群聊与 DSH 智能体会话连接起来。

一句话产品：让用户在常用的 QQ 聊天中与 DSH 智能体交互，并让回复回到发起对话的原聊天。

当前功能规划：QQ 私聊、群聊绑定到 DSH 会话或工作区；转发文字和图片；在智能体一轮正常完成后定向回传回复；通过设置项管理收发开关和连接参数。

后续规划：先完善消息可靠性、部署与回归测试，再评估上下文组织、记忆和人格规则；之后考虑抽象多渠道接口，以及微信、ESP32 等设备接入。后续规划不作为当前已完成能力承诺。

技术方案：QQ / OneBot 11 接入消息；Java 中转服务处理消息翻译、合并、限流、队列和 QQ 收发；DSH JS 插件负责绑定解析、心跳、轮询、消息投递和会话事件转发。当前 GitHub 仓库提供 DSH 插件代码，不包含配套 Java 中转服务源码。

演示地址：目前为本机 Demo，公网运行地址尚未提供。

1.2 队员风采

项目	陈安东（3124004085）	杨旭东（3124004109）	李家乐（3124004096）	陈宇轩（3124004089）	李兆希（3124004099）	李梓弘（3124004100）
性格	无欲无求	插科打诨	开朗阳光	积极向上	喜欢摸鱼	沉稳细心
擅长技术	Java、MySQL	后端开发	LangChain、Python	Vibe Coding	模型调用	HTML、CSS
兴趣爱好	玩游戏、打乒乓球	玩游戏、跑步	篮球	听音乐、打游戏	打游戏	听音乐
希望角色	项目统筹	后端开发	PM	前端	后端	前端

1.3 团队合照

1.4 项目愿景

我们希望黑猫计划先成为一套稳定、可控的智能体交互系统：让 Agent 能在 QQ 等日常渠道中持续理解上下文，并在获得授权后连接设备与现实环境。未来通过记忆与规则机制提升互动的连贯性，同时让用户明确掌握数据、权限与开关。我们会按真实使用场景逐步扩展，先验证消息链路，再探索多渠道和硬件交互，让智能体能力融入日常生活。

2. 选题报告

2.1 从智能体能力到日常聊天场景

智能体可以通过对话理解用户意图，但用户通常需要进入提供智能体能力的独立应用。本项目选择把已有的 DSH 智能体连接到 QQ 私聊和群聊，让用户可以在熟悉的聊天窗口发起对话，再由 DSH 会话中的 Agent 处理消息。

黑猫计划的重点是打通聊天渠道与智能体会话之间的连接，并处理消息来源、绑定关系和回复去向；模型能力本身由 DSH 中的 Agent 提供，项目不另造一个通用聊天模型。

2.2 目标用户与使用场景

目标用户：希望通过 QQ 私聊或群聊使用 DSH 智能体的用户，以及负责配置聊天绑定的项目维护者。

场景一：私聊咨询。用户在已绑定的 QQ 私聊中发送消息，系统将消息投递至指定 DSH 会话；Agent 完成回复后，系统将结果发回该私聊。

场景二：群聊互动。管理员将 QQ 群绑定到 DSH 会话或工作区，成员在群里发起对话，系统按消息来源将回复送回原群，避免发到其他绑定聊天。

场景三：配置与排查。维护者调整收发开关和连接参数，并通过日志查看消息投递、确认和失败状态。

2.3 核心问题与解决思路

项目围绕三个具体问题设计：QQ 消息如何进入正确的 Agent 会话；Agent 的一轮回复如何回到发起对话的聊天；在多聊天绑定、图片传递或服务暂时不可用时，如何减少串线和消息丢失。

因此，系统将 QQ / OneBot 11、Java 中转服务和 DSH 跳板插件分开：Java 服务负责 QQ 消息与业务队列，DSH 插件负责识别绑定目标、投递到会话并监听回复事件。

2.4 项目亮点：按来源聊天定向回复

黑猫计划的核心亮点是将回复与触发它的 QQ 聊天关联。消息进入 DSH 时记录来源；只有 Agent 正常完成一轮后才回传，并按来源定向发送。这样，即使多个 QQ 私聊或群聊接入同一系统，回复也能回到对应聊天；在 DSH 中手动发起、没有 QQ 来源的对话不会被误发到 QQ。

2.5 当前范围与后续计划

当前 Demo 聚焦 QQ 私聊、群聊与 DSH 会话之间的绑定和双向消息链路，支持文字、图片、来源定向回复及设置、日志等基础能力。稳定性和部署优化仍需继续完成。长期记忆、人格规则、微信、多渠道扩展、ESP32 和环境交互均属后续规划，不属于当前版本已完成能力。

3. 需求分析文档

3.0 迭代记录

迭代	时间	目标	主要内容	状态
当前 Demo	截至 2026-11-08	打通 QQ 与 DSH 的消息闭环	私聊、群聊双向收发；文字、图片和日志链路；设置与绑定能力	PPT 报告本机演示已跑通
迭代 1：稳定链路	2026-11-09 ～ 2026-11-22	提升可靠性和可部署性	补齐依赖和部署脚本，完善异常告警、消息可靠性和回归测试	计划中
迭代 2：上下文与人格	2026-11-23 ～ 2026-12-06	扩展 Agent 的连续互动能力	在 Java 侧组织上下文、提示词、记忆读写和规则约束	后续规划
迭代 3：渠道解耦	2026-12-07 ～ 2026-12-20	降低对单一聊天渠道的依赖	抽象 Channel 接口；在 QQ 链路稳定后评估微信接入	后续规划
迭代 4：设备与环境	2026-12-21 ～ 2027-01-03	探索智能体与现实环境互动	先验证 ESP32 单一传感器事件，再设计空间状态和 Agent 响应	后续规划

3.1 引言

编写目的：描述黑猫计划当前版本的功能范围、前后端职责、接口和验收方式，帮助团队开发、测试和课程验收时使用同一套范围说明。

项目背景：智能体通常需要用户进入独立应用发起对话。本项目希望探索将 DSH 智能体接入 QQ 私聊和群聊的方式，使用户可以在熟悉的聊天场景中发起请求，并让回复按来源回到原聊天。

当前范围：本阶段聚焦 QQ 与 DSH 的消息连接、会话绑定、来源定向回复、文字及图片传递和设置管理。长期记忆、人格规则、微信、ESP32 与空间环境模型均属于后续规划，不计入当前版本验收。

3.2 项目标志与产品定位

项目标志：仓库现有插件图标以两个端点和连接线表示 DSH 与 QQ 之间的消息桥接，本博客暂以该图标作为项目标志。

一句话定位：面向 QQ 聊天场景的 DSH 智能体连接系统，让消息进入指定智能体会话，并让完成的回复回到对应来源聊天。

范围（做什么 / 暂不做什么）：当前版本做 QQ 私聊与群聊绑定、双向文字和图片消息传递、回复定向、设置和日志支持；当前版本不承诺公网稳定运行，也不包含长期记忆、人格演化、微信或硬件联动。

3.3 思维导图

mindmap root((黑猫计划智能体)) 当前演示功能 QQ私聊与群聊接入 绑定到DSH会话或工作区 QQ到DSH 文字消息 图片消息 DSH到QQ 整轮正常完成后回复 按来源聊天定向返回 设置与运维 收发开关和连接参数 日志与消息状态 系统组成 QQ与OneBot11 Java中转服务 消息队列与确认 消息翻译和合并 限流与拆段 图片和身份处理 DSH跳板插件 会话绑定解析 心跳与队列轮询 会话事件监听 图片附件与去重 可靠性要求 投递成功后再确认 失败消息可重试 回复不能串线 手动发起的DSH对话不外发 后续规划 稳定性与部署 上下文与提示词 记忆和人格规则 渠道解耦与微信评估 ESP32传感器与环境交互

若博客平台不支持渲染 Mermaid，可将上述代码粘贴到 https://mermaid.live 导出图片后替换。

3.4 类图

下图展示仓库中可见的 DSH 插件模块及其依赖关系。Java 中转服务源码未包含在当前仓库中，因此图中只标出外部服务边界，不推测其内部类结构。

classDiagram class DshCatLinker { +apply(ctx, config) +wireModules() } class Bridge { +get(path) +post(path, body) } class Inbound { +tick() +deliver(message) +ack(ids) } class Outbound { +handleSessionEvent(session, event) +reportCompletedTurn() } class Presence { +tick() +listBoundChats() } class BindingSource { +refresh() } class TurnOrigin { +remember(sessionId, chatKey) +get(sessionId) } class SessionResolver { +resolveBinding(binding) +pickSessionInWorkspace() } class WorkspaceIndex { +snapshot() +pickSession() } class RemoteSettings { +refresh() } class Logger { +log(message) +failOnce(message) } class JavaRelay { <<external service>> } class OneBot11 { <<external service>> } DshCatLinker --> Bridge DshCatLinker --> Inbound DshCatLinker --> Outbound DshCatLinker --> Presence DshCatLinker --> RemoteSettings Inbound --> Bridge Inbound --> SessionResolver Inbound --> TurnOrigin Outbound --> Bridge Outbound --> TurnOrigin Presence --> SessionResolver Presence --> BindingSource BindingSource --> Bridge SessionResolver --> WorkspaceIndex RemoteSettings --> Bridge Bridge --> JavaRelay JavaRelay --> OneBot11

3.5 功能描述

2.5.1 前端与用户交互

• QQ 私聊与群聊：用户在已绑定的聊天中发送消息，系统按绑定关系将消息送到 DSH 会话；智能体回复后发回触发对话的聊天。
• 文字与图片：支持双向文字和图片消息。入站图片无法接收时保留文字内容，并通过日志记录处理情况。
• DSH 设置页：提供中转地址、令牌、工作区会话选择方式、总开关、双向收发开关、心跳间隔、队列轮询间隔和请求超时的配置；支持读取、修改、保存和放弃未保存修改。配置读取或保存失败时显示提示。
• 聊天绑定：支持将私聊或群聊绑定到指定 DSH 会话，或绑定到工作区并按策略选择会话。绑定数据从 Java 设置服务读取；若远端设置未配置则可使用插件本地配置。

2.5.2 后端与智能体接入

• DSH JS 跳板插件：监听 DSH 会话事件；从 Java 中转服务轮询待投递消息；根据 QQ 聊天绑定解析目标会话；将消息投递给 Agent；在一轮正常结束后上报回复。
• 来源定向与防误发：插件记录入站消息与会话的来源关系。出站回复只发往本轮来源聊天；在 DSH 内手动发起、没有 QQ 来源的对话不转发到 QQ。
• 投递确认：只有消息成功投递给 DSH 会话后才确认；临时失败的消息保留给后续轮询处理。完成轮次按来源回复，并对重复的轮次进行去重。
• Java 中转服务：答辩 PPT 报告该服务负责 OneBot 通信、消息翻译、连续消息合并、限流、拆段、图片处理、身份与提示词渲染，以及消息队列和确认。由于 Java 源码未包含在提供的仓库中，这些内容以 PPT 所述本机 Demo 能力为准，仍需补充源码链接和独立验证信息。

3.6 接口需求

以下路径来自 DSH 插件代码中的接口定义，表示插件对 Java 服务的调用约定；Java 端具体实现需以中转服务源码为准。

方法	路径	用途
GET	/api/v1/dsh/outbox?limit=	拉取待投递到 DSH 的消息
POST	/api/v1/dsh/ack	确认已经成功投递的消息
POST	/api/v1/dsh/events	上报一轮完成的 DSH 回复
POST	/api/v1/dsh/presence	上报当前负责的聊天和会话状态
GET	/api/v1/settings/bindings	获取绑定配置
GET / POST	/api/v1/linker/config	读取或保存跳板配置

QQ 消息入口使用 OneBot 11。当前系统的调用方向为 DSH 跳板插件访问 Java 服务；Java 服务不反向调用 DSH 宿主接口。

3.7 非功能需求

类别	需求
可靠性	消息投递失败时不提前确认；正常完成的回复按来源发回；重复消息需可识别和诊断。
正确性	私聊、群聊与 DSH 会话的绑定关系明确；不同来源的回复不得串线；未完成轮次不作为正常回复回传。
可配置性	收发开关、绑定方式及轮询、心跳、请求超时等参数可配置。
可观测性	能从日志追踪消息来源、投递和异常；配置读取或保存失败时有提示。
隐私与权限	消息仅在用户配置的聊天与会话绑定范围内传递；总开关可停止收发；令牌应按部署配置妥善管理。
可维护性	QQ 通信、Java 中转和 DSH 插件职责分开；新增渠道前先验证现有 QQ 链路。
可部署性	当前材料显示本机 Demo；公网部署、持续运行和安全配置尚未作为已完成能力验证。

3.8 验收标准

编号	验收项	验收标准	验证方式
A1	私聊入站	已绑定私聊中的文字消息进入指定 DSH 会话；未绑定聊天不误投递	在 QQ 私聊发送测试消息，检查对应 DSH 会话和日志
A2	群聊入站	已绑定群聊中的消息进入绑定目标，发言人身份信息可识别	在测试群发送消息，检查会话内容和来源日志
A3	定向回复	Agent 正常完成一轮后，回复只回到触发该轮的 QQ 聊天	分别从私聊和群聊触发并核对回复位置
A4	非正常结束	中断或未正常完成的轮次不作为完整回复发到 QQ	中断一轮生成并检查 QQ 端
A5	图片传递	图片可用时按设计双向传递；入站图片不可用时文字内容仍可投递	分别发送图片并模拟图片不可用情形
A6	确认与重试	DSH 投递失败时不提前确认；后续重试可再次处理	模拟目标会话不可用，检查队列和日志
A7	开关与配置	关闭总开关或收发开关后相应方向停止；保存配置后按设置生效	在设置页切换开关并进行收发验证
A8	消息隔离与去重	多个聊天的回复不串线，同一轮完成消息不重复发送	对多个绑定聊天连续提问并观察日志
A9	日志诊断	可按消息链路查看来源、投递结果和主要失败原因	触发正常和失败用例后检查日志

答辩 PPT 报告当前本机 Demo 已演示私聊、群聊双向收发以及图片和日志链路。

4. 项目小结

项目小结：黑猫计划当前完成了 DSH 与 QQ 之间的本机消息闭环 Demo，重点验证聊天绑定、来源定向和文字、图片消息的双向传递。下一阶段先把已有链路的部署、异常处理和稳定性测试做好，再决定是否扩展长期记忆、人格规则、多渠道和硬件场景。