前言¶
DeepSeek Harness（DSH）的 Agent 會話主要在 Web 界面裏進行。人不在電腦前時，任務發不出去；在 Web 裏跑完一輪對話，手機端也沒有即時提醒。常見做法是另開一套消息機器人或自己寫轉發層，還要處理公網暴露、權限白名單等問題。
dsh-qq-bridge 是 DSH Web profile 下的客戶端插件，由 TomoyoNatsume 維護，把 QQ 消息轉成 DSH Agent 會話請求，再把回覆發回 QQ。鏈路走本機 NapCat / OneBot 或騰訊官方 QQ Bot，不需要爲 bridge 單獨開放外部端口。
這是什麼¶
dsh-qq-bridge 的定位很直接：QQ 發消息 → bridge → DSH Agent → QQ 收回復。
QQ 發送消息 -> NapCat / OneBot -> dsh-qq-bridge -> DSH Agent -> QQ 回覆
插件以 DSH bundle 形式掛載，npm 包名爲 @yachangchang/dsh-qq-bridge（當前版本 1.0.5），許可證 MIT。社區目錄頁在 SkillHub，源碼在 GitHub（11 stars）。SkillHub 是獨立的 DSH 插件社區站點，與 DeepSeek / 幻方無官方從屬關係。
默認推薦 NapCat / OneBot：用一個 QQ 號登錄 NapCat，從手機 QQ 給自己發消息即可，不必額外準備機器人小號。也支持雙號模式（一個號登錄 NapCat 收消息，另一個號發指令）和騰訊官方 QQ 開放平臺機器人兩種路徑。
核心功能¶
下面這些是 README 中已列出的能力，安裝前可按需對照。
QQ 遙控 Agent
白名單用戶直接在 QQ 裏發任務，插件轉成 DSH live session，最終回覆發回 QQ。
工作區、模型與會話控制
支持 bridge 側指令 /dir、/new-session、/models、/model、/reasoningEff、/permission 等，也支持用自然語言切換常用設置。
定時提醒與 memo
v0.4.0 起支持一次性定時任務；v1.0.0 起可在 Web UI 中配置。例如在 QQ 裏說「請在 2026 年 9 月 1 號中午 12 點提醒我提交報告」，到點後在同一會話觸發 Agent 並主動提醒。數據通過 DSH storageDomain 持久化。
Web 會話完成提醒
非 QQ 發起的 Web 會話結束後，可主動給管理員 QQ 發提醒。QQ 發起的會話只返回實際 Agent 回覆。官方 QQ Bot 路徑下不支持該功能。
雙接入路徑
- NapCat / OneBot：本機個人使用，功能完整，社區方案，小號存在被強制下線的風險。
- 騰訊官方 QQ Bot：需 AppID、AppSecret，對接更穩，功能較少；主動提醒有額度限制，插件在官方模式下默認關閉
notifications.agentReply.enabled。
安裝與啓用¶
系統要求¶
- 已安裝 DSH，
dsh web可正常啓動。 - Linux / WSL2 環境；Node.js 20+。自動安裝嚮導目前只適配 Linux / WSL2，原生 Windows 建議先用 WSL2。
- NapCat 路徑：本機需先安裝 NapCat CLI，並有一個可掃碼登錄的 QQ 號。
- 官方 QQ Bot 路徑：需在 QQ 開放平臺 創建機器人，提供 AppID、AppSecret。
安裝插件¶
推薦從 npm 安裝穩定版：
pnpm dsh plugin --profile web add @yachangchang/dsh-qq-bridge
也可以直接從 GitHub 安裝當前倉庫：
pnpm dsh plugin --profile web add github:TomoyoNatsume/dsh-qq-bridge
插件會寫入 dsh.profile.bundles。剛安裝時默認 enabled: false，不會連接 QQ，也不會啓動 bridge。
NapCat 安裝（選 NapCat 路徑時）¶
Linux / WSL2 推薦：
cd ~
curl -o napcat.sh https://raw.githubusercontent.com/NapNeko/NapCat-Installer/main/script/install.sh
bash napcat.sh --docker n --cli y
確認命令可用：
napcat help
只需安裝 NapCat CLI，不必手動先啓動 QQ 後臺；設置頁保存配置時會按填寫的 QQ 號執行 napcat start <QQ>。
在 Web UI 中啓用¶
- 啓動
dsh web，打開左下角「設置」，進入QQ bridge。 - 選擇接入方式（NapCat / OneBot 或騰訊官方 QQ Bot），填寫管理員、Agent 模型等，點擊「保存配置」。NapCat 分支會檢測本機 NapCat，並自動寫入 OneBot 正向 WebSocket 配置和 token（默認
127.0.0.1:3001）。 - 保存成功後，在 QQ 裏發送
ping驗證。若無響應，執行napcat log <你的QQ號>或查看~/Napcat/log/napcat_<你的QQ號>.log，確認是否已掃碼登錄。
官方 QQ Bot 首次配置時，setup 會生成一次性 pair <code>，用管理員 QQ 發給機器人即可完成 adminOpenId 配對。
典型用法¶
驗證連通後，README 建議依次嘗試以下消息：
ping
當前工作目錄是什麼
列出當前工作目錄下的目錄和文件
/dir /home/xxx/project
/models
/model deepseek-v4-pro
/reasoningEff high
/permission workspace-write
/new-session
幫我把工作目錄改到 /home/xxx/project
請在 2026 年 9 月 1 號中午 12 點提醒我提交報告
收到有效 QQ 指令後，插件會先回復 agent.ackMessage（默認「收到，正在處理…」），設爲空字符串可關閉。
常用 Agent 配置示例：
agent:
provider: deepseek-official
model: deepseek-v4-pro
cwd: "~"
preset: dsh-qq-bridge
ackMessage: 收到，正在處理...
cwd：QQ Agent 默認工作目錄；/dir <目錄>會覆蓋當前 QQ 會話的後續 session 目錄。preset：QQ 會話專用 preset；普通 Web 會話不選它則不會套用 QQ 回覆風格 skill。
NapCat 模式配置示例：
platform: napcat
napcat:
wsUrl: ws://127.0.0.1:3001
token: "<NapCat OneBot access token>"
配置修改推薦在 Web UI 的 QQ bridge 頁面完成；手動排查時可查看 ~/.dsh/profiles/web/cordis.patch.yml，改完後重啓 dsh web。
適用場景與注意¶
適合誰
- 需要在手機 QQ 裏遠程給 DSH Agent 派任務、收回復的開發者。
- 希望 Web 會話結束後收到 QQ 提醒、不想長期盯着瀏覽器進度的人（NapCat 路徑）。
- 已有 NapCat 環境，或願意在 QQ 開放平臺註冊官方 Bot 的用戶。
使用前務必瞭解
- 權限邊界：插件以當前
dsh web進程的用戶權限運行，Agent 能訪問的工作區、文件和網絡範圍與 DSH 一致。安裝前應閱讀源碼與 MIT 許可證，確認白名單和管理員配置符合你的安全要求。 - 接入方式差異：NapCat 功能更全但非官方；官方 Bot 更穩但不支持 Web 會話完成自動提醒，且主動消息有額度限制。
- 單號 / 雙號模式：雙號模式推薦新用戶直接使用；單號模式可收 Agent 完成提醒，但可能收不到消息提示。登錄 DSH 的 NapCat 賬號不建議用極不常用的小號。
- 已知限制：當前不支持通過 QQ「我的電腦」會話完整交互；這類消息可被日誌捕獲，但回覆鏈路不完整。
- 舊版遷移：從舊版 setup 遷移到 bundle 時，啓動會自動清理
cordis.patch.yml裏舊的id: dsh-qq-bridge插入項，並在同目錄留下.bak備份。
更完整的架構說明見倉庫 docs/project-overview.md，使用導圖見 docs/usage-guide.html。
結尾¶
dsh-qq-bridge 把 QQ 接進 DSH 的 Agent 鏈路，在本機完成消息轉發，兼顧遙控、模型切換、定時提醒和 Web 會話通知。DSH 生態的理念是「一切皆插件」；若你需要在移動端驅動鯨魚娘，可以先從 ping 驗通，再按場景選 NapCat 或官方 Bot 路徑。
