dsh-qq-channel
将列入允许列表的 QQ 私信通过 OneBot 11 路由到隔离的 dsh 工作区。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:riki-forsure/dsh-napcatqq-remote#d12e01076ad00c3f5c4fcec2cfe83a688530b3beQq Channel 以 dsh-qq-channel 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
dsh-napcatqq-remote 是一个基于 NapCatQQ / OneBot 11 的 DeepSeek Harness（dsh）远程操控插件。指定 QQ 联系人可以像平时私聊一样给家里或服务器上的 dsh 安排工作，并在 QQ 中收到处理结果。
这个仓库不是 QQ 客户端，也不包含模型。运行时需要三个部分：已经登录机器人 QQ 的 NapCatQQ、本插件，以及负责实际执行任务的 DeepSeek Harness。
qq_send_file、qq_send_image 把真实文件发回 QQ。deepseek-v4-flash-vision-exp 等视觉模型时，可读取 OneBot 图片、文件形式的常见图片，以及能够从 QQ NT 缓存或消息中取得真实图像的 QQ 表情。/新任务 或 /new 清除当前映射，下一条普通消息自动新建一段独立对话；旧对话不会被删除。/历史 查看该联系人自己的最近 10 段 QQ 对话，再用 /切换 2 或完整会话 ID 恢复；不同联系人的历史不会互相出现。表情识别有一个必要条件：插件必须取得真实图片数据。如果 NapCat 只提供表情编号或元数据，而且本地缓存也没有对应图片，视觉模型只能看到编号或摘要，不能看到表情画面。
| 指令 | 作用 | 是否调用模型 |
|---|---|---|
/状态、/status | 查看 OneBot 连接、白名单数量、QQ 工作区、模型、语气和实际 Agent 预设。 | 否 |
/新任务、/new | 解除该联系人当前会话的映射；下一条普通消息才会创建新会话。 | 否 |
/历史、/history | 查看当前联系人自己的最近 10 段 QQ 历史对话，并标记当前项。 | 否 |
/切换 2、/switch 2 | 切换到刚刚 /历史 列出的第 2 段对话。任务运行中会拒绝切换。 | 否 |
/切换 <完整会话ID>、/switch <完整会话ID> | 精确恢复属于当前联系人、当前 QQ 工作区的历史对话。 | 否 |
其他私聊文字、图片和文件都会作为工作请求交给 dsh。仅发送 /状态 不会提前创建对话。
| 你现在的情况 | 建议阅读 | 大致用时 |
|---|---|---|
| 希望一条命令准备 DSH、NapCat、OneBot、本插件与桌面快捷方式 | 从零开始：自动安装 | 主要等待下载，最后人工登录 QQ |
| dsh 和 NapCatQQ 都已安装、都能正常运行 | 快速安装插件 | 5～10 分钟 |
| dsh 已能正常对话，懂基本终端操作，但尚未安装 NapCatQQ | NapCatQQ 安装与接入 | 15～30 分钟 |
| dsh、WSL2 或 NapCatQQ 还没有准备好，希望从零开始 | 从零开始详细教程 | 30～60 分钟 |
| 希望交给 Codex、Claude Code 等本地 Agent 安装 | Agent 安装说明 | 先让 Agent 检查环境 |
| 已经装好但 QQ 没反应 | 按现象排查 | 视问题而定 |
不确定选哪条时，从详细教程开始；每份教程顶部也能切换到其他路线。
把下面整段连同仓库地址交给一个能访问本机终端的 Agent：
请完整安装并配置 https://github.com/riki-forsure/dsh-napcatqq-remote 。
先完整读取仓库根目录 AGENTS.md，自动检测并复用现有 NapCat Shell/Desktop 与 DSH；缺少的 WSL、Node、DSH、dsh-routing-suite、OneBot、本插件和桌面快捷方式都按文档装好。
把流程推进到 NapCat 的 QQ 登录/设备验证界面后再让我操作；登录完成后继续自动写入 OneBot 与插件配置并验收。保留现有配置、会话、语气和工作区，输出中隐藏 QQ 号与所有 Token。
根目录的 AGENTS.md 已包含环境分流、准确命令、配置字段、保留规则和验收清单，因此只给 Agent 仓库地址也能快速理解安装方式。
白名单联系人发送 QQ 私聊
↓
机器人 QQ（登录在 NapCatQQ Shell/OneKey 或 Desktop）
↓ OneBot 11 WebSocket 事件
dsh-napcatqq-remote
├─ 验证发送者白名单
├─ 保存和转换附件
├─ 选择联系人对应的会话
└─ 把消息送进 QQ 渠道工作区
↓
DeepSeek Harness（模型、Agent、工具、工作区与会话）
↓
插件组织文字/图片/文件/表情回复
↓
NapCatQQ 发回原联系人
| 组件 | 负责什么 | 不负责什么 |
|---|---|---|
| NapCatQQ | 登录机器人 QQ，把 QQ 消息转换为 OneBot 11 事件，并执行发送消息接口。 | 不运行模型，也不处理工作任务。 |
| 本插件 | 连接 OneBot、校验白名单、管理附件和联系人会话、把结果发回 QQ。 | 不替代 QQ、NapCatQQ 或 dsh。 |
| DeepSeek Harness（dsh） | 调用模型和工具，在指定工作区真正读取文件、运行命令并完成任务。 | 不直接登录 QQ。 |
配置里涉及两类 QQ 号：
| 名称 | 是谁 | 填在哪里 |
|---|---|---|
| 机器人 QQ | NapCatQQ 中登录、负责收发消息的账号 | 通常自动识别；需要时填 botSelfId |
| 白名单联系人 | 给机器人发消息、希望使用 dsh 的发送者 | 必须填入 allowedContacts |
allowedContacts 填消息发送者，不是机器人自己的 QQ 号。
/新任务 后只是解除映射；下一条普通消息才新建对话。/新任务 删除；发送 /历史 可查看当前联系人的最近 10 段，发送 /切换 2 可继续其中一段。/历史 与 /切换 按联系人隔离；一个白名单联系人看不到另一个联系人的 QQ 会话。.qq-inbox 范围内，模型可按权限读取和处理。qq_send_file、qq_send_image、qq_send_face、qq_send_mface 回传真实内容。face 会保留表情编号，并尽量从 QQ NT 本地缓存解析图片。mface / marketface 会保留商城表情的 ID、包 ID、key 和摘要；只有拿到图片时才交给视觉模型。默认 stylePromptFile 为空，因此插件不会自动模仿任何联系人。回复语气来自实际选中的 dsh Agent 预设，通常以直接完成任务、清楚汇报结果为主。
启用自定义语气时，把 contact-style.example.md 复制到：
~/.dsh/qq-channel/contact-style.md
修改复制后的文件，再把它的绝对路径写入 config.json 的 stylePromptFile。模板适合填写称呼、长短、语气词、标点习惯、汇报方式和对话示例。详细步骤见完整安装教程的语气章节。
新安装推荐候选顺序是：
router-standard → standard → minimal
router-standard 是 Agent 预设名称，不是模型名称。自动安装会在缺少路由预设时，从独立开源项目 dsh-routing-suite 安装它；本仓库没有复制或捆绑对方源码。既有部署若使用自定义的 router-auto 会被保留。路由套件安装失败或用户选择不安装时，插件仍会回退到 DSH 自带的 standard 或 minimal，QQ 渠道可以继续工作。
DeepSeek Harness 仍在快速迭代，npm 的稳定标签、预览标签与 GitHub 源码快照可能不完全同步。本项目的自动安装器会保留已有兼容 DSH；全新安装使用 @deepseek-ai/dsh@latest，低于 0.1.0-rc.6 才自动升级。0.1.x 版本通过运行时能力检测兼容，未来版本则提示完成 QQ 端验收。
本插件把 DSH API 包声明为可选 peer dependency，不会在插件目录私装另一套旧 API。手动从 GitHub ZIP/源码安装时，应在测试后执行：
pnpm prune --prod --config.auto-install-peers=false
这样可避免新旧对象混用产生类似 commit is not a function 的错误。ask_user_question 限制、模型选择等可选接口不存在时，插件会走兼容路径并在日志中说明。
~/.dsh/qq-channel/
├── config.json 本地连接、白名单、模型和语气配置
├── contact-style.md 可选语气模板
└── state.json 联系人与 dsh 会话的映射
~/dsh-work/qq-channel-workspace/
├── .qq-inbox/<联系人QQ>/ 收到的普通文件
└── corpus/live/<联系人QQ>/
└── dialogue.jsonl QQ 渠道实时对话语料
图片正文由 dsh attachment 服务保存。配置、Token、QQ 号、聊天记录、附件和语料都属于本地运行数据，不应提交到 GitHub。
config.json 或语气文件后，需要完整重启 dsh 才会重新读取。| 现象 | 先检查 | 详细位置 |
|---|---|---|
| QQ 消息完全没有回复 | 发送者白名单、机器人在线、NapCat WS、IP/端口、Access Token | 分层故障排查 |
/状态 能回复，普通任务不回复 | dsh WebUI 的模型、提供商 ID、实际预设和任务状态 | dsh 与模型层 |
| dsh 显示等待 OneBot | NapCat 使用的是 WebSocket Server，不是反向 WS；端口从 WSL 可达 | NapCat 连接测试 |
| 两个白名单账号都没有反应 | JSON 数组、DSH_QQ_CONTACTS 环境变量覆盖、重启是否完成 | 插件层排查 |
第二个联系人没有出现在 state.json | 它是否发过普通任务；仅 /状态 不创建会话 | 会话验证 |
| WebUI 慢或启动后不跳转 | 是否启动了多个 dsh web 抢占 3080 | dsh 层排查 |
| 表情只能看到编号 | 消息或 QQ NT 缓存是否存在真实图片，emojiRoot 是否正确 | 图片与表情配置 |
| 项目 | 与本项目的关系 |
|---|---|
| deepseek-ai/deepseek-harness | DeepSeek Harness 主程序与插件运行环境；必需。 |
| NapNeko/NapCatQQ | QQ 到 OneBot 11 的实现；必需。新安装默认使用其 Windows Shell OneKey 包。 |
| NapNeko/NapCatQQ-Desktop | 独立的图形化管理器；已有 Desktop 时会保留并复用，但界面与 Shell WebUI 不同。 |
| botuniverse/onebot-11 | 本插件使用的消息和接口规范。 |
| yjh051108/dsh-routing-suite | 可选且推荐的路由预设来源；未复制、修改或捆绑其源码。 |
这些项目分别遵循自己的许可证和发布节奏。本项目是独立社区插件，不代表上述项目，也不与腾讯或 QQ 官方存在隶属关系。
git clone https://github.com/riki-forsure/dsh-napcatqq-remote.git
cd dsh-napcatqq-remote
pnpm install --frozen-lockfile
pnpm test
贡献、问题报告和安全说明分别见 CONTRIBUTING.md 与 SECURITY.md。版本变化见 CHANGELOG.md。