前言¶
在 DeepSeek Harness（DSH）里做 QQ 侧的智能体，常见有两条路：走腾讯官方开放平台（AppID、审核、回调），或用 OneBot 协议端接普通 QQ 号。后者上手快，但要自己接协议、管会话和权限，还要把模型、工具和人设接到 DSH 上。qfish 是面向第二种路线的 DSH 客户端插件：通过 NapCat / OneBot v11 连 QQ，聊天、记忆、工具和控制台都在一个 npm 包里，模型与会话直接走 DSH，中间不夹额外中间层。下面介绍它是什么、能做什么，以及如何安装与配置。
这是什么¶
qfish（包名 qfish，仓库 hyun20202023-ui/dsh-qfish）由维护者 hyun20202023-ui 发布，在 SkillHub 目录中归类为客户端插件。当前 npm 版本为 0.3.8，许可证 MIT，要求 DSH 引擎 ^0.2.1-rc.2。
一句话定位：用普通 QQ 号（经 NapCat）当机器人，在群聊与私聊里以人设、记忆和工具与 DSH 智能体联动，并自带网页控制台。
核心功能¶
资料中明确的能力可归纳为以下几块。
聊天与人设¶
- 人设写在 markdown 里；短句为主，带情绪与好感度，群聊收敛、私聊更放开。
- 按人存储记忆，满额会压成摘要；群聊与私聊共用同一份记忆。会话过长会轮换上下文，旧内容压成摘要，私聊轮换时还会写入一条记忆。
- 会学习群里人的口头禅与句式；黑话分「骂人」与「普通」两张表，用于听懂与回嘴。
- 切句按语气断句发多条，不按字数均分。
多模态与 B 站¶
- 发图可看图说话。
- 发 B 站链接会处理字幕、画面、弹幕、热评后再回复；过长会直接说明，不假装看完。处理在临时会话中完成，主线只留摘要。
工具与运维¶
搜图、联网、音乐卡片、提醒、群管理、跨群发消息；在具备后台权限时可执行服务器命令（见 README 工具说明）。
控制台与客户端集成¶
内置网页控制台：会话、记忆、社交、观看记录、配置、日志集中管理。DSH 页面右下角有入口（默认指向本机 127.0.0.1:8090）。花费相关参数（上下文轮换、看图批量、视频时长与频率等）可在控制台调整。
接入方式说明¶
插件走 OneBot / NapCat，不依赖 QQ 官方机器人开放平台。协议端存在被风控的可能，适合自用、群里拟人陪伴；若要面向公众的正式产品，需自行对比官方 Bot 的稳定性与合规要求。
安装与启用¶
安装插件¶
推荐从 npm 安装（README 原文命令）：
dsh plugin add qfish
装完后重启 DSH。
也可在 profile 中通过 Git 依赖安装：
pnpm add git+https://github.com/hyun20202023-ui/dsh-qfish.git
并在 profile 的 package.json 里把 qfish 放进 dsh.profile.bundles，再安装依赖。
准备 NapCat¶
需要：已能正常对话的 DSH（含默认模型）、一个 QQ 小号、OneBot v11 协议端 NapCat（含 WebSocket）。
本地：安装 NapCat 并登录 QQ；网络配置中新建 WebSocket 服务器，端口 3001，消息格式 array。
服务器（Docker 示例，来自 README）：
docker run -d --name napcat --restart unless-stopped \
-p 3001:3001 -p 6099:6099 \
-v /opt/napcat:/app/napcat \
mlikiowa/napcat-docker:latest
3001：插件连接的 WebSocket；6099：NapCat 网页扫码；3001建议仅本机访问，勿暴露公网。
插件配置要点¶
在 DSH → 插件设置 → qfish（配置的 id 与 name 均应为 qfish）中填写，例如：
| 配置项 | 说明 |
|---|---|
url |
ws://127.0.0.1:3001 |
accessTokenRef |
NapCat 设了 token 时才填 |
consoleEnabled |
true |
consoleListen |
本地 127.0.0.1；服务器改为 0.0.0.0 |
consolePort |
默认 8090（占用会顺延） |
consoleToken |
可留空自动生成；服务器建议自设长串 |
respondToPrivate |
本地默认 false；服务器常用 true |
userAccessMode / userIds |
默认 allowlist，空名单即全拒 |
groupAccessMode / groupIds |
同上 |
默认 全拒：allowlist 且名单为空时不会回复任何消息。白名单示例：
userAccessMode: allowlist
userIds: ["你的QQ号"]
groupAccessMode: allowlist
groupIds: ["你的群号"]
全部放开示例：
userAccessMode: blocklist
userIds: []
groupAccessMode: blocklist
groupIds: []
按需配合 respondToPrivate: true、groupMentionOnly: false。服务器部署需放行 8090（控制台）与 6099（NapCat 网页）。
登录与打开控制台¶
扫码可在 NapCat 网页或控制台「行为参数」中的二维码完成。控制台地址须带 token：
http://地址:8090/?t=令牌
token 来自配置 consoleToken、文件 <profile>/onebot-data/console-token.txt，或 DSH 启动日志中「控制台已启动」那一行的完整 URL。服务器上请将 consoleListen 设为 0.0.0.0 并放行端口；远程访问勿仅靠 DSH 右下角按钮（其内置地址为 127.0.0.1）。
更细的机制、行为参数与排障见仓库 docs/USER-GUIDE.md。
典型用法流程¶
按 README 快速开始，顺序可概括为：
- 执行
dsh plugin add qfish并重启 DSH。 - 启动 NapCat，确认 WebSocket 3001、格式 array。
- 在插件设置中填
url、访问控制白名单及控制台相关项。 - 扫码登录 QQ。
- 用带
?t=的地址打开控制台，调整人设、行为与花费相关参数。 - 在已加入且已列入
groupIds的群中 @ 机器人，或在允许私聊时发私聊验证收发。
维护者在 README 中还提供了一段可交给 DSH 自动执行的安装指令（判断环境、装依赖、起 NapCat、写 cordis.patch.yml、验证日志），适合让本机 DSH 按步排查；使用时需确认 profile 内已有默认模型（如 agent-default-model），否则新会话可能无法拿到模型。
适用场景与注意¶
适合：已在用 DSH、愿意用 NapCat 养 QQ 小号、希望在群/私聊里做拟人陪伴、看图看视频、联网与群工具，并希望通过网页管记忆与配置的用户。
注意：
- 插件以当前 DSH 进程权限运行；安装前宜查看 源码 与 MIT 许可证，自行评估协议端风险与服务器命令等高危能力。
- 社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；「一切皆插件」是 DSH 生态理念，不等同于官方应用商店。
- 交流群（README）：QQ 群 480910887。
结尾¶
qfish 把 OneBot 接入、拟人对话、记忆与多模态、工具链和网页控制台收进一个 DSH 插件，适合用普通 QQ 号在 DSH 上快速试跑 QQ 机器人。目录与文档：SkillHub 插件页、GitHub 仓库。
