前言¶
在 DeepSeek Harness（DSH）里做智能体，常见做法是接 Web、终端或自建 HTTP 通道。个人 QQ 仍依赖 OneBot 生态里的 NapCat 等客户端：要自己下载运行包、填 API token、事件上报地址，还要单独维护登录与进程。下面介绍的 dsh-qq-access 把 NapCat 托管、消息自动回复、本地归档和 QQ 空间读写收进一个 DSH 插件，并在 Harness 左侧栏提供「QQ 接入」管理面板。
这是什么¶
dsh-qq-access 由社区维护者 Applepinea 发布，在 SkillHub 插件目录 中归类为客户端插件（GitHub 约 2 stars）。它面向「用 Harness 驱动个人 QQ」的场景：在 Windows x64 上可固定官方 NapCat Node 运行包（v4.18.41）、自动生成连接配置、随插件启停进程；Linux、macOS、Windows ARM 当前走外部 NapCat 模式（见仓库 docs/EXTERNAL_MODE.md）。
插件以 MIT 许可发布自写代码；NapCat 与官方运行包遵循上游许可，使用前请阅读仓库 来源说明。插件在 DSH 进程权限下运行，安装前应自行核对源码与许可证。
核心功能¶
资料中明确的能力如下。
| 能力 | 说明 |
|---|---|
| NapCat 托管（Windows x64） | 校验并解压固定版本运行包，生成 API token、事件签名与本机连接；扫码页就绪后可自动打开浏览器 |
| QQ 聊天 | 接收可上报的入站消息；默认私聊自动回复，群聊在被 @ 时回复；图片可转为模型可见内容（PNG/JPEG/GIF/WEBP，单条最多 4 张，可通过 reply.vision 关闭） |
| 历史与归档 | 本地归档、搜索，或调用 QQ 历史接口分页查询；retentionDays 默认 30 天 |
| QQ 空间 | 独立 Edge 浏览器登录，读取可见文字，在留言板发表纯文本留言（不含说说评论、发说说、相册导出等） |
| 管理面板 | 左侧栏「QQ 接入」：自动回复开关、批量窗口与轮询、回复范围白名单、NapCat 托管、人格编辑、在线状态 |
访问范围受登录账号权限与 QQ 接口数据限制；语音等媒体仍以类型占位文字呈现。聊天内容在回复或主动查询时会进入 Harness 配置的模型服务。
安装与启用¶
环境要求（README）：Node.js 22.14+（建议 24 LTS）、提供当前 Agent/工具接口的 Harness（文档参考 0.2.1-rc.4），QQ 空间功能需要 Edge 浏览器。package.json 声明 node >=22.14.0、dsh >=0.2.1-rc.3。
Windows x64 新安装¶
- 解压插件源码目录
dsh-qq-access，在 PowerShell 中执行：
npm ci
node cli.mjs setup
按提示输入要接入的 QQ 号。管理员 QQ 可留空（仅在本地 Harness 管理）；若填写，应使用另一个 QQ 号，避免登录号自身出站消息触发自动回复。setup 在 Windows x64 上会启用托管模式、生成密钥并下载运行包（约 118.3 MiB，首次需联网）。默认配置路径为 %USERPROFILE%\.dsh-qq-access\config.json，不会覆盖已有文件。下载失败可执行 node cli.mjs napcat-install 重试。
- 从 GitHub Releases 下载最新
dsh-qq-access.tgz，在 Harness 桌面版插件管理中指定完整路径；或在 CLI / Web profile 中：
dsh plugin --profile web add C:/Plugins/dsh-qq-access.tgz
dsh web
profile 须与实际启动环境一致。插件会自动启动 NapCat，扫码页就绪后打开浏览器；未弹出时可执行 node cli.mjs napcat-login。
- QQ 空间需单独登录（与 NapCat 状态分离）：
node cli.mjs qzone-login
在独立 Edge 窗口登录同一 QQ 号，回终端按回车。关闭登录窗口后再调用空间相关工具。
从旧版升级¶
解压新源码、npm ci 后运行 node cli.mjs napcat-enable（备份配置并启用托管），再在 Harness 中用新 .tgz 替换并重载。无 napcat 配置段时仍为 external 模式。
离线准备 NapCat 包¶
从 NapCat v4.18.41 官方 Release 下载 NapCat.Shell.Windows.Node.zip，在已启用托管的配置下：
node cli.mjs napcat-install --archive C:/Downloads/NapCat.Shell.Windows.Node.zip
文件须与固定版本及 SHA256 一致，不能用 Framework、普通 Shell 或 OneKey 包代替。
典型用法¶
在 Harness 对话中可直接用自然语言驱动工具，README 示例包括：
- 查看 QQ 接入状态
- 列出我的群
- 读取好友 234567890 最近 30 条消息
- 给 QQ 234567890 发：今晚八点见
- 在 QQ 234567890 的空间留言板留言：周末快乐
发送与留言使用唯一 request_id；重试须复用同一标识。只有 status: sent 表示成功，pending 或 uncertain 需先核对实际结果。
常用配置项（修改后重载插件）：
| 配置项 | 默认与用途 |
|---|---|
napcat.mode |
新 Windows x64 为 managed；外部接入为 external |
reply.private / reply.group |
私聊默认开；群聊默认 mention，可改 off 或 all |
access.privateMode / access.groupMode |
默认 all，可改 allowlist 或 disabled |
access.privateIds / access.groupIds |
白名单，QQ 号/群号为字符串 |
ownerIds |
管理员私聊账号，默认空 |
persona |
称呼、性格、语气、回复习惯 |
retentionDays |
默认 30 |
普通联系人仅允许本会话聊天与历史查询；管理员权限以传输层确认的私聊账号为准，群内按普通成员处理。
排查时可只读执行：
node cli.mjs doctor
尚未启动 Harness 或未扫码时，API 离线不一定表示安装失败；qq_status.napcat.state 可查看启动、待扫码、在线状态。
适用场景与注意¶
适合：已在用 DSH、希望把个人 QQ（私聊、群 @、可选空间留言）接到同一 Harness 工作流，并在 Windows x64 上减少手工维护 NapCat 的用户。
注意：
- 插件以当前 DSH 进程权限运行；安装前请检查源码与许可证，勿在未审计的环境中接入生产 QQ 号。
- README 说明本版在 Linux 做过本地测试并校验运行包，未在 Windows 完成真实 QQ 登录与空间验收；空间页面结构、权限与验证码需在目标机器自行验证。
- API、上报与登录页仅绑定本机；端口冲突时退出冲突程序或改配置后重载。控制台日志在配置对应
data/napcat/logs/console.log，可能含敏感信息，仅用于本机排查。 - DSH 社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；插件来自社区，非官方应用商店条目。
结尾¶
dsh-qq-access 把 NapCat 托管、QQ 消息 AI 回复（含可选图片理解）、本地归档与 QQ 空间留言，以及左侧栏可视化人设与权限管理，收敛为单一 DSH 客户端插件。需要细节、外部模式说明与验证记录时，以仓库为准：
- 目录页：https://www.skillhub.cn/plugins/Applepinea/dsh-qq-access
- GitHub：https://github.com/Applepinea/dsh-qq-access
