dsh-napcat-bridge

DeepSeek Harness × NapCat QQ 接入插件 —— 让 DSH Agent 在 QQ 群聊 / 私聊中对话、检索历史、收发图片文件。

✨ 功能特性

QQ 群聊 / 私聊全场景接入：基于 NapCat（OneBot 11 协议）反向 WebSocket 连接。
QQ 会话专属预设（qq-session）：构建期与运行时单一真相源（SSOT）自动同步，专属注入 QQ 工具集，彻底杜绝工具向 Web UI 常规会话泄露；深度补齐工作区、跨平台 Shell（Windows pwsh / Linux bash）、Web 搜索、交互提问与技能系统，并抑制多余快照。
用户侧静默出站体系：遵循「用户侧静默原则」，废除纯文本直接推流；文本出站统一由 send_qq_message 工具驱动，由模型根据入站标头 [消息ID: <id>] 与上下文逻辑自主决定是否引用原消息（reply_to）或艾特用户（at_user）。
工具与回合解耦（单 Agent 顺手维护）：执行出站工具不强行终止回合，模型在回复用户后可在同一轮次中顺手调用记忆或表情管理工具，自然平稳终结。
两层记忆体系：群聊会话记忆 + 用户跨群互通画像，Markdown 文件存储，提供 read_memory、create_memory、edit_memory 三大工具；写入侧按“用户画像 / Session 规则 / 群聊画像总预算”三个独立字符预算硬拒绝超限落盘，注入侧保持文件内容原子；彻底摒弃独立后台回顾 Agent。
表情包管理体系：受 face_enabled 配置门控，提供查表情（list_faces）、发表情（send_face）、收录好图（collect_face）与库容维护/LRU 淘汰（manage_faces）闭环工具链；另有群聊 react_message 贴表情轻量表态。
串行发送与多媒体交互：单对端串行出站队列，避免并发乱序；支持私聊文件入站自动落盘、群共享文件索引查询（list_group_files）、动态资源拉取（fetch_chat_resource）与合并转发展开（expand_forward_message）。
卡片消息通用提取器：自动提取 QQ 卡片（小程序、分享、音乐等）的标题与链接。
群聊主动回复策略：普通消息窗口期聚合轮询 + 潜水超时破冰 + Agent 繁忙丢弃 + 夜间免打扰，支持「仅回复文本内容」过滤并赋予 Agent [结束] 静默决策权。
纯两字中文斜杠命令：/新建、/会话、/用量、/停止、/模型、/权限、/思考、/状态、/帮助，内置严格的管理员白名单权限隔离与 per-session 状态管理。
WebUI 设置面板：通过 DSH Web UI 配置所有插件参数，6 大 Tab 分组（连接身份、人格与准则、回复配置、记忆、表情包、黑话学习），全部 30 项参数支持 volatile 动态热更新。

📦 安装与启动

前置条件

DeepSeek Harness (npm install -g @deepseek-ai/dsh) >= 0.2.0
NapCat（QQ 机器人协议端）
Node.js >= 22.12.0（受 better-sqlite3 原生依赖约束，低于此版本无法加载）
pnpm >= 9.0.0（仅源码安装需要）

方式一：从 npm 安装（推荐）

# 安装到 DSH 的 web profile
dsh plugin --profile web add dsh-napcat-bridge

# 或安装到全局默认环境
dsh plugin add dsh-napcat-bridge

[!NOTE] Desktop 版没有 dsh CLI，请在 DSH「插件 → 添加插件」里直接输入包名 dsh-napcat-bridge 安装。

npm 包已内置编译产物与 cordis.patch.yml，安装后重启 DSH 即生效，无需本地构建。better-sqlite3 自带 8 平台预编译二进制，常规安装不触发 node-gyp 编译。

方式二：从源码安装（开发 / 调试）

[!IMPORTANT] DSH 通过 package.json 的 main -> dist/index.js 与 dsh.bundle.patch 加载插件。在执行 link 之前必须先运行 pnpm build 生成编译产物与预设同步补丁。

git clone https://github.com/Jiangsubei/dsh-napcat-bridge.git
cd dsh-napcat-bridge

# 安装依赖并编译（内置 sync-patch 预设同步、tsc 编译与客户端面板构建）
pnpm install
pnpm build

# link 安装到 DSH 的 web profile
dsh plugin --profile web add link:.

配置与运行

NapCat 添加反向 WebSocket 客户端：在 NapCat WebUI（默认 http://127.0.0.1:6099/webui）的网络配置中新增反向 WebSocket 客户端：
- URL：ws://127.0.0.1:8080/（需与插件 ws_port 对齐）
- Token：与插件 ws_token 保持一致（若留空则此处留空）
- 心跳周期：30000 ms，重连间隔：3000 ms
启动 DSH：
```
dsh --profile web
```
DSH WebUI 配置核心参数：访问 DSH Web UI（默认 http://127.0.0.1:3080/），进入 dsh-napcat-bridge 设置卡片：
- bot_qq（必填项）：填写机器人的 QQ 号，用于过滤自身消息防死循环，并作为群聊识别 @机器人的基准。
- admins：填写管理员 QQ 号，授权执行斜杠命令。
- 其他可选参数（人设、主动回复、记忆预算、表情包开关等）按需调整，保存即时热更新生效。

⚙️ 运行时配置 (30 项)

配置卡片在 WebUI 中分为 6 个 Tab：

1. 连接身份 (Connection)

参数	类型	默认值	说明
`ws_port`	`number`	`8080`	WebSocket 监听端口（NapCat 连接目标，变更时服务热重启）
`ws_token`	`string`	`""`	连接鉴权 Token（留空不鉴权）
`bot_qq`	`string`	`""`	机器人自身 QQ 号（核心必填项，自循环防护与识别锚点）
`admins`	`string[]`	`[]`	管理员 QQ 号白名单（斜杠命令授权）
`aliases`	`string[]`	`[]`	助手点名别名（群聊点名唤醒）
`image_ttl_days`	`number`	`7`	外来图片与多媒体缓存本地保留天数（过期定时清理）

2. 人格与准则 (Persona & Behavior)

参数	类型	默认值	说明
`persona`	`string`	(内置)	助手的人格设定（注入 System Prompt 动态段）
`behavior`	`string`	(内置)	行为约束准则（注入 System Prompt 动态段）

3. 回复配置 (Proactive)

参数	类型	默认值	说明
`proactive_reply_enabled`	`boolean`	`false`	启用群聊主动回复功能总开关
`proactive_interval_mins`	`number`	`3`	主动回复轮询窗口期（分钟，期间有新消息才唤醒）
`proactive_buffer_size`	`number`	`10`	主动回复滑动窗口消息保留条数
`proactive_random_enabled`	`boolean`	`false`	启用群聊普通消息随机概率唤醒
`proactive_random_probability`	`number`	`0.05`	普通消息随机唤醒概率（0~1，`0.05` 即 5%）
`proactive_cooldown_mins`	`number`	`10`	主动回复冷却时间（分钟，防止频繁插话）
`proactive_only_text`	`boolean`	`false`	仅回复纯文本内容（多模态媒体消息不主动触发）
`proactive_idle_enabled`	`boolean`	`false`	启用潜水超时主动唤醒（冷场破冰冒泡）
`proactive_idle_timeout_mins`	`number`	`120`	潜水超时阈值（分钟）
`proactive_night_dnd`	`boolean`	`true`	夜间免打扰 (每日 23:00~08:00 暂停主动回复)

4. 记忆 (Memory)

参数	类型	默认值	说明
`memory_storage_dir`	`string`	`".dsh/napcat/napcat_memory"`	记忆 Markdown 文件根存储目录
`user_profile_budget_chars`	`number`	`2200`	单个用户画像文件的写入上限（跨群聊/私聊通用）
`session_memory_budget_chars`	`number`	`2200`	单个 Session 规则文件的写入上限（群聊/私聊统一）
`group_memory_total_budget_chars`	`number`	`8000`	群聊注入时所有活跃群友画像合计的字符预算；Session 规则不计入

5. 表情包 (Face)

参数	类型	默认值	说明
`face_enabled`	`boolean`	`false`	控制新建会话是否在预设中装载表情包工具集（保存对后续新会话生效）
`face_store_max`	`number`	`100`	本地表情库存储容量上限（张）
`face_store_dir`	`string`	`".dsh/napcat/faces"`	本地表情库文件存储目录
`face_sub_type`	`number`	`1`	OneBot 11 发送表情使用的 sub_type 字段值
`face_evict_policy`	`string`	`"evict_lru"`	库容满额淘汰策略 (`reject` 拒绝 / `evict_lru` 淘汰最久未用)

6. 黑话学习 (Slang)

参数	类型	默认值	说明
`slang_enabled`	`boolean`	`true`	控制新建会话是否装载黑话工具集与注入黑话上下文（保存对后续新会话生效）
`slang_budget_chars`	`number`	`5000`	黑话知识库字符预算上限
`slang_storage_path`	`string`	`".dsh/napcat/slang/slang.md"`	黑话 Markdown 文档保存路径

配置下线说明：群聊强制引用/艾特死配置（group_reply_quote、group_reply_at）及空回复行为面板已下线。出站回复遵循「用户侧静默原则」，是否引用与艾特统一由大模型通过 send_qq_message 工具参数（reply_to、at_user）自主决策。独立后台 Agent 参数也已清退下线。

🛠️ 开发与构建

git clone https://github.com/Jiangsubei/dsh-napcat-bridge.git
cd dsh-napcat-bridge
pnpm install
pnpm typecheck
pnpm test:quick    # 快速单测
pnpm build         # 同步预设、类型编译与构建 WebUI 产物

🧪 测试

本项目遵循严格的契约测试先行与真实装配验证规范，覆盖专属预设单一真相源同步、出站静默工具流、单 Agent 顺手提炼、表情包闭环、两层记忆体系与斜杠命令等场景（60 套件 500+ 测试用例）。

pnpm test          # 完整测试（先执行 pnpm build 再执行测试）
pnpm test:quick    # 快速执行测试（跳过 build）

📚 文档索引

面向使用者的标准开源文档统一存放于 docs/ 目录：

快速上手 (docs/getting-started.md)：环境依赖、安装步骤、NapCat WS 配置与验证指南。
系统架构 (docs/architecture.md)：模块总览、生命周期装配、用户侧静默出站体系、记忆与表情体系。
配置说明 (docs/configuration.md)：WebUI 6 大 Tab 完整配置项、默认值与迁移说明。
工具与命令 (docs/tools-and-commands.md)：send_qq_message 等 13 个 Agent 工具契约与 9 个纯两字中文斜杠命令。
故障排查 (docs/troubleshooting.md)：出站静默未调用工具、预设隔离、连接异常等问题排查指引。

📄 License

MIT

dsh-napcat-bridge

DeepSeek Harness × NapCat QQ 接入插件 —— 让 DSH Agent 在 QQ 群聊 / 私聊中对话、检索历史、收发图片文件。

✨ 功能特性

QQ 群聊 / 私聊全场景接入：基于 NapCat（OneBot 11 协议）反向 WebSocket 连接。
QQ 会话专属预设（qq-session）：构建期与运行时单一真相源（SSOT）自动同步，专属注入 QQ 工具集，彻底杜绝工具向 Web UI 常规会话泄露；深度补齐工作区、跨平台 Shell（Windows pwsh / Linux bash）、Web 搜索、交互提问与技能系统，并抑制多余快照。
用户侧静默出站体系：遵循「用户侧静默原则」，废除纯文本直接推流；文本出站统一由 send_qq_message 工具驱动，由模型根据入站标头 [消息ID: <id>] 与上下文逻辑自主决定是否引用原消息（reply_to）或艾特用户（at_user）。
工具与回合解耦（单 Agent 顺手维护）：执行出站工具不强行终止回合，模型在回复用户后可在同一轮次中顺手调用记忆或表情管理工具，自然平稳终结。
两层记忆体系：群聊会话记忆 + 用户跨群互通画像，Markdown 文件存储，提供 read_memory、create_memory、edit_memory 三大工具；写入侧按“用户画像 / Session 规则 / 群聊画像总预算”三个独立字符预算硬拒绝超限落盘，注入侧保持文件内容原子；彻底摒弃独立后台回顾 Agent。
表情包管理体系：受 face_enabled 配置门控，提供查表情（list_faces）、发表情（send_face）、收录好图（collect_face）与库容维护/LRU 淘汰（manage_faces）闭环工具链；另有群聊 react_message 贴表情轻量表态。
串行发送与多媒体交互：单对端串行出站队列，避免并发乱序；支持私聊文件入站自动落盘、群共享文件索引查询（list_group_files）、动态资源拉取（fetch_chat_resource）与合并转发展开（expand_forward_message）。
卡片消息通用提取器：自动提取 QQ 卡片（小程序、分享、音乐等）的标题与链接。
群聊主动回复策略：普通消息窗口期聚合轮询 + 潜水超时破冰 + Agent 繁忙丢弃 + 夜间免打扰，支持「仅回复文本内容」过滤并赋予 Agent [结束] 静默决策权。
纯两字中文斜杠命令：/新建、/会话、/用量、/停止、/模型、/权限、/思考、/状态、/帮助，内置严格的管理员白名单权限隔离与 per-session 状态管理。
WebUI 设置面板：通过 DSH Web UI 配置所有插件参数，6 大 Tab 分组（连接身份、人格与准则、回复配置、记忆、表情包、黑话学习），全部 30 项参数支持 volatile 动态热更新。

📦 安装与启动

前置条件

DeepSeek Harness (npm install -g @deepseek-ai/dsh) >= 0.2.0
NapCat（QQ 机器人协议端）
Node.js >= 22.12.0（受 better-sqlite3 原生依赖约束，低于此版本无法加载）
pnpm >= 9.0.0（仅源码安装需要）

方式一：从 npm 安装（推荐）

# 安装到 DSH 的 web profile
dsh plugin --profile web add dsh-napcat-bridge

# 或安装到全局默认环境
dsh plugin add dsh-napcat-bridge

[!NOTE] Desktop 版没有 dsh CLI，请在 DSH「插件 → 添加插件」里直接输入包名 dsh-napcat-bridge 安装。

npm 包已内置编译产物与 cordis.patch.yml，安装后重启 DSH 即生效，无需本地构建。better-sqlite3 自带 8 平台预编译二进制，常规安装不触发 node-gyp 编译。

方式二：从源码安装（开发 / 调试）

[!IMPORTANT] DSH 通过 package.json 的 main -> dist/index.js 与 dsh.bundle.patch 加载插件。在执行 link 之前必须先运行 pnpm build 生成编译产物与预设同步补丁。

git clone https://github.com/Jiangsubei/dsh-napcat-bridge.git
cd dsh-napcat-bridge

# 安装依赖并编译（内置 sync-patch 预设同步、tsc 编译与客户端面板构建）
pnpm install
pnpm build

# link 安装到 DSH 的 web profile
dsh plugin --profile web add link:.

配置与运行

NapCat 添加反向 WebSocket 客户端：在 NapCat WebUI（默认 http://127.0.0.1:6099/webui）的网络配置中新增反向 WebSocket 客户端：
- URL：ws://127.0.0.1:8080/（需与插件 ws_port 对齐）
- Token：与插件 ws_token 保持一致（若留空则此处留空）
- 心跳周期：30000 ms，重连间隔：3000 ms
启动 DSH：
```
dsh --profile web
```
DSH WebUI 配置核心参数：访问 DSH Web UI（默认 http://127.0.0.1:3080/），进入 dsh-napcat-bridge 设置卡片：
- bot_qq（必填项）：填写机器人的 QQ 号，用于过滤自身消息防死循环，并作为群聊识别 @机器人的基准。
- admins：填写管理员 QQ 号，授权执行斜杠命令。
- 其他可选参数（人设、主动回复、记忆预算、表情包开关等）按需调整，保存即时热更新生效。

⚙️ 运行时配置 (30 项)

配置卡片在 WebUI 中分为 6 个 Tab：

1. 连接身份 (Connection)

参数	类型	默认值	说明
`ws_port`	`number`	`8080`	WebSocket 监听端口（NapCat 连接目标，变更时服务热重启）
`ws_token`	`string`	`""`	连接鉴权 Token（留空不鉴权）
`bot_qq`	`string`	`""`	机器人自身 QQ 号（核心必填项，自循环防护与识别锚点）
`admins`	`string[]`	`[]`	管理员 QQ 号白名单（斜杠命令授权）
`aliases`	`string[]`	`[]`	助手点名别名（群聊点名唤醒）
`image_ttl_days`	`number`	`7`	外来图片与多媒体缓存本地保留天数（过期定时清理）

2. 人格与准则 (Persona & Behavior)

参数	类型	默认值	说明
`persona`	`string`	(内置)	助手的人格设定（注入 System Prompt 动态段）
`behavior`	`string`	(内置)	行为约束准则（注入 System Prompt 动态段）

3. 回复配置 (Proactive)

参数	类型	默认值	说明
`proactive_reply_enabled`	`boolean`	`false`	启用群聊主动回复功能总开关
`proactive_interval_mins`	`number`	`3`	主动回复轮询窗口期（分钟，期间有新消息才唤醒）
`proactive_buffer_size`	`number`	`10`	主动回复滑动窗口消息保留条数
`proactive_random_enabled`	`boolean`	`false`	启用群聊普通消息随机概率唤醒
`proactive_random_probability`	`number`	`0.05`	普通消息随机唤醒概率（0~1，`0.05` 即 5%）
`proactive_cooldown_mins`	`number`	`10`	主动回复冷却时间（分钟，防止频繁插话）
`proactive_only_text`	`boolean`	`false`	仅回复纯文本内容（多模态媒体消息不主动触发）
`proactive_idle_enabled`	`boolean`	`false`	启用潜水超时主动唤醒（冷场破冰冒泡）
`proactive_idle_timeout_mins`	`number`	`120`	潜水超时阈值（分钟）
`proactive_night_dnd`	`boolean`	`true`	夜间免打扰 (每日 23:00~08:00 暂停主动回复)

4. 记忆 (Memory)

参数	类型	默认值	说明
`memory_storage_dir`	`string`	`".dsh/napcat/napcat_memory"`	记忆 Markdown 文件根存储目录
`user_profile_budget_chars`	`number`	`2200`	单个用户画像文件的写入上限（跨群聊/私聊通用）
`session_memory_budget_chars`	`number`	`2200`	单个 Session 规则文件的写入上限（群聊/私聊统一）
`group_memory_total_budget_chars`	`number`	`8000`	群聊注入时所有活跃群友画像合计的字符预算；Session 规则不计入

5. 表情包 (Face)

参数	类型	默认值	说明
`face_enabled`	`boolean`	`false`	控制新建会话是否在预设中装载表情包工具集（保存对后续新会话生效）
`face_store_max`	`number`	`100`	本地表情库存储容量上限（张）
`face_store_dir`	`string`	`".dsh/napcat/faces"`	本地表情库文件存储目录
`face_sub_type`	`number`	`1`	OneBot 11 发送表情使用的 sub_type 字段值
`face_evict_policy`	`string`	`"evict_lru"`	库容满额淘汰策略 (`reject` 拒绝 / `evict_lru` 淘汰最久未用)

6. 黑话学习 (Slang)

参数	类型	默认值	说明
`slang_enabled`	`boolean`	`true`	控制新建会话是否装载黑话工具集与注入黑话上下文（保存对后续新会话生效）
`slang_budget_chars`	`number`	`5000`	黑话知识库字符预算上限
`slang_storage_path`	`string`	`".dsh/napcat/slang/slang.md"`	黑话 Markdown 文档保存路径

配置下线说明：群聊强制引用/艾特死配置（group_reply_quote、group_reply_at）及空回复行为面板已下线。出站回复遵循「用户侧静默原则」，是否引用与艾特统一由大模型通过 send_qq_message 工具参数（reply_to、at_user）自主决策。独立后台 Agent 参数也已清退下线。

🛠️ 开发与构建

git clone https://github.com/Jiangsubei/dsh-napcat-bridge.git
cd dsh-napcat-bridge
pnpm install
pnpm typecheck
pnpm test:quick    # 快速单测
pnpm build         # 同步预设、类型编译与构建 WebUI 产物

🧪 测试

pnpm test          # 完整测试（先执行 pnpm build 再执行测试）
pnpm test:quick    # 快速执行测试（跳过 build）

📚 文档索引

面向使用者的标准开源文档统一存放于 docs/ 目录：

快速上手 (docs/getting-started.md)：环境依赖、安装步骤、NapCat WS 配置与验证指南。
系统架构 (docs/architecture.md)：模块总览、生命周期装配、用户侧静默出站体系、记忆与表情体系。
配置说明 (docs/configuration.md)：WebUI 6 大 Tab 完整配置项、默认值与迁移说明。
工具与命令 (docs/tools-and-commands.md)：send_qq_message 等 13 个 Agent 工具契约与 9 个纯两字中文斜杠命令。
故障排查 (docs/troubleshooting.md)：出站静默未调用工具、预设隔离、连接异常等问题排查指引。

📄 License

MIT

Jiangsubei/dsh-napcat-bridge

dsh-napcat-bridge

✨ 功能特性

📦 安装与启动

前置条件

方式一：从 npm 安装（推荐）

方式二：从源码安装（开发 / 调试）

配置与运行

⚙️ 运行时配置 (30 项)

1. 连接身份 (Connection)

2. 人格与准则 (Persona & Behavior)

3. 回复配置 (Proactive)

4. 记忆 (Memory)

5. 表情包 (Face)

6. 黑话学习 (Slang)

🛠️ 开发与构建

🧪 测试

📚 文档索引

📄 License

Community comments

Jiangsubei/dsh-napcat-bridge

dsh-napcat-bridge

✨ 功能特性

📦 安装与启动

前置条件

方式一：从 npm 安装（推荐）

方式二：从源码安装（开发 / 调试）

配置与运行

⚙️ 运行时配置 (30 项)

1. 连接身份 (Connection)

2. 人格与准则 (Persona & Behavior)

3. 回复配置 (Proactive)

4. 记忆 (Memory)

5. 表情包 (Face)

6. 黑话学习 (Slang)

🛠️ 开发与构建

🧪 测试

📚 文档索引

📄 License

Community comments