QQ Bridge Harness for DeepSeek Harness

一个面向 QQ 私聊与群聊的有状态 Agent harness，以 DeepSeek Harness（DSH）为模型、会话与工具宿主，通过 SnowLuma 接入 QQ。它在消息收发之外，管理上下文装填、记忆、人物身份、发送计划、等待、主动行为和运行观测。

项目基于 Derpyu520/qq-bridge 扩展，遵循仓库 LICENSE。当前代码版本为 v0.4.0，通过独立运行目录接入 DSH；二代工具驱动聊天是主路径，一代聊天保留兼容入口。

在 Windows 上首次安装？可以直接看 四步安装。

当前架构

QQ ↔ SnowLuma / OneBot ↔ Bridge ↔ DSH 会话与模型
                           ↑          ↓
                     收发与状态能力 ← 受控工具调用
                           ↑
                   组件宿主 · 本地 Console

部分	职责
DSH	模型请求、Agent 会话、工具循环、预设及插件加载。
Bridge	QQ/DSH 连接、真实账号核验、入站交付、发送与回执，以及供组件调用的能力。
组件宿主	通过钩子与服务组织提示词、记忆提取、互动策略、预算和调度；组件可以配置、停用和重载。
Console	编辑规则、管理会话、检查实际上下文与工具轨迹、查看预算、任务、反馈和连接状态。

业务调度统一经过 life-scheduler，消息投递仍需经过相应的会话、权限、预算与发送计划检查。预设定义能力组合，人设卡定义身份与行为边界，当前风格配置和对话示范校准表达；它们分别管理，严肃任务也须保持事实准确与内容完整。

Console 分层

公开受管实例的控制台默认地址为 http://127.0.0.1:3200/。当前导航包含八个业务层，以及独立的组件注册层：

层	名称	主要内容
C	上下文与记忆	人设、词条、黑话、绰号、心情、记忆与会话背景。
T	工具接口与协议	工具参考与开关、Games、Codex Peer、提示词注入实验。
E	环境与执行	普通/管理员环境、预设、网页操作与监督、脚本、媒体、会话与审批。
L	生命周期与编排	来信唤醒、发送与等待、主动行为及相关组件。
O	可观测与运维	运行总览、实际请求可视化、日记、反馈与运维入口。
V	验证与评估	测试与评估入口。
G	治理与安全	权限、安全与治理配置。
S	个人思想与知识	本地资料的导入、校验、查询与按需注入。

层级是管理和开发的职责划分，不等于每次请求都注入所有组件。具体工具是否可用，由实际预设、工具开关与运行守卫共同决定。

一次聊天如何运行

1. 收件与触发：桥接核对 bot 账号、会话名单与入站身份，记录消息。私聊和群聊使用不同的触发策略；群聊还受唤醒概率与频率限制。
2. 交付上下文：装填本次任务、历史记录、待处理消息和当前状态。回复前必须把完整正文及所需引用交给当前处理回合；缺失或截断时先补读。
3. 模型与工具循环：模型可以读取消息、查询资料、更新状态、执行允许的任务，并通过工具发送 QQ。二代模式下，模型普通文本属于内部输出，不会自动作为 QQ 消息发送。
4. 投递与回执：实际发送经过统一检查；只有成功结果及相应回执才能作为已发送、已回复的依据。未知结果不自动当作成功或盲目重发。
5. 等待与收尾：等新消息、等对方说完分别处理；无人回复时由逐次增长的收尾概率提供硬性结束保护。收到真实新消息后仍可继续处理。

QQ 身份以真实 QQ 号区分，昵称相同、前缀相同或改名不合并人物；一个具体绰号只确认到一个 QQ。消息关联使用真实收件 seq、messageId 与工具调用 ID，不为展示补编收件编号。

五段上下文

每次请求按以下逻辑分区组织；这些分区与 API 的 system/user/assistant/tool 消息角色不是一一对应关系。

顺序	分区	内容与更新方式
1	系统上下文	面向模型的硬规则、权限边界及受保护的基础设定。
2	稳定用户上下文	会话背景、组件行为规则及相对稳定的资料。
3	聊天与工具历史	已处理的聊天记录与工具调用/返回，保留时间线和调用对应关系。
4	本次来信与待处理	最新桥接处理要求及未读、已读但未完成处理的消息。
5	当前动态资料	当前心情、日程、话题建议、临时画像等，只保留最新有效状态。

工具定义通过独立的 tools 请求字段提供，不作为一段聊天历史追加。稳定内容尽量前置、变化频繁的状态集中在末尾，有利于减少重复和复用请求前缀；实际缓存命中仍取决于模型服务与请求内容。

O 层 → 可视化 context 展示捕获的实际请求，区分 QQ 消息、系统与上下文、工具调用/返回。它保留一次持续处理的初始请求，并滚动记录上一次与最新请求；不会为了展示而额外调用模型。C36 负责收件状态索引，已读与已回复采用双时间戳。缺少证据时保留未核验状态，不从实时状态补造旧快照。

记忆与资料的分工

类型	用途
QQ 号人物档案	跨会话的稳定作息、爱好、关系等事实；低频更新，以可核对的证据为依据。
持久化记忆	本会话重要事实、今日临时画像、未完成事项和展示日记。
轻量记忆	当前话题、待说想法、短窗口行为印象；随聊天快速变化。
S 层知识	用户导入的资料，经校验后查询、阅读和按需注入，不当作聊天中已经发生的事件。

有依据的信息可以向人物档案、日程或主动时段沉淀，不凭一次猜测生成稳定关系。记忆候选不代替正式聊天输入，记忆整理回合在发送入口禁止模型发 QQ。

发送、主动行为与预算

• 聊天意愿与心情分开：前者评估用户是否有空，后者描述主观互动状态；两者参与主动概率及回复条数、深度的调节，表达风格由心情与当前风格配置决定。
• 话题与主动会话协同：话题发起、旧话题跟进、继续等待具有可配置权重，并分别受冷却、次数和发送计划限制。日程、定时主动消息等由统一调度器处理。
• 等待分工明确：等新消息控制本次工具愿意等待的时长；静默窗口判断对方是否说完。无人回复收尾的初始概率与每次增量可在 Console 调整。
• 预算约束：支持令牌/费用统计及分阶段处理。低预算待处理队列按私聊、群聊 @、群聊普通消息分别限长；恢复处理仍受触发策略约束。群聊机械回应要求真实 @ 或已核实引用 bot。
• 任务隔离：独立任务、后台学习和网页摘要采用各自预设；工具返回、内部输出、任务产物与真实 QQ 投递分别记录。

安装与首次启动

Windows 四步安装

1. 准备环境。 使用 Windows x64、Node.js 24.20.0 或更新版本、DSH Desktop 和 QQ 桌面版。首次打开 DSH，完成模型配置，找到目标 DSH 数据目录，然后退出 Desktop。从 v0.4.0 Release 下载 qq-bridge-public-0.4.0.tgz 和 SHA256SUMS，并将两个文件放在同一目录。

2. 准备新实例。 在 PowerShell 粘贴下面的命令，按本机情况替换四个路径。$target 必须是尚不存在的目录，且它的父目录已经存在。SnowLuma 会自动下载和校验。

   $package = 'C:/Downloads/qq-bridge-public-0.4.0.tgz'
   $dshHome = 'C:/DSHHome'
   $target = 'C:/Bots/public-bot'
   $bootstrap = 'C:/BotSetup'
   
   $checksum = Join-Path (Split-Path -Parent $package) 'SHA256SUMS'
   $filename = [regex]::Escape((Split-Path -Leaf $package))
   $entry = Get-Content -LiteralPath $checksum | Where-Object { $_ -match ('^[0-9a-f]{64}\s+' + $filename + '$') }
   $expected = ($entry -split '\s+')[0]
   if ((Get-FileHash -LiteralPath $package -Algorithm SHA256).Hash -ne $expected) { throw '发行包 SHA-256 不匹配' }
   npm install --prefix $bootstrap $package --ignore-scripts --no-audit --no-fund
   if ($LASTEXITCODE -ne 0) { throw '临时安装目录准备失败' }
   $installer = Join-Path $bootstrap 'node_modules/qq-bridge-public/scripts/install.mjs'
   node $installer --target $target --dsh-home $dshHome --profile desktop
   

3. 核对后应用。 确认输出的 conflicts 为空，候选文件指向正确的实例和 DSH profile，且 Desktop 和其他 profile 写入者均已退出。然后在同一个 PowerShell 窗口执行：

   $candidate = Join-Path $target '.instance-install/candidate.json'
   node $installer --apply-plan $candidate --writers-stopped
   

4. 启用并检查。 重新打开 DSH Desktop，在插件设置启用新注册的公开 Bot。在该实例的启动面板设置自己的 QQ 账号和允许交互的联系人或群，启动服务并按提示完成 QQ 登录。打开默认控制台 http://127.0.0.1:3200/，确认 QQ 和 DSH 已连接。

已有实例升级、端口冲突处理、失败回滚和源码打包见 完整安装指南。升级前先保留现有配置、角色、会话和状态，再按指南审查新旧源码差异。

可选能力

能力	额外准备
Codex Peer	安装并登录 Codex，使用 Codex Peer 自己的显式安装流程；bot 迁移保留现有 Peer。
网页登录与 DOM 操作	Chrome/Edge 或对应 Playwright 浏览器；自行完成登录，管理员开发能力默认关闭。
视频抽帧与音频转换	FFmpeg；未安装时对应工具报告缺依赖。
图片生成	自行配置兼容服务、模型与 API 凭据。
API 余额与预算监督	配置自己的模型服务凭据；账号金额仅向管理员提供。
网页/校园监控	自行配置目标网址、适配器与登录态，按站点隔离浏览器会话。
S 层资料	通过 Console 导入、校验自己的本地资料包，并配置按需注入。

开发与验证

拥有源	内容
src/bridge.js、src/bridge-core/	连接、协议、状态与能力分发。
plugins/qq-components/	组件声明、钩子、服务、规则及相关测试。
dsh/agent-presets/、plugins/qq-agent-presets/	预设源与 DSH 接入模块；生成的 patch 不作为第二份编辑源。
console/	前端页面、样式与交互的拥有源，public/console.html 为构建产物。
scripts/build-dsh-bundle.mjs	生成根组合包声明及客户端入口。

npm test
npm run build:console
npm run lint:console
npm run build:bundle -- --check
node scripts/build-agent-preset-patches.mjs --check
npm run privacy:check

版本变更与验证记录见 v0.4.0 Release。发行附件提供 SHA-256 校验值和打包源码清单。

测试使用临时副本、测试状态与桩 QQ/DSH；模拟通过不代表实际账号已登录、模型已完成任务或 QQ 已成功投递。真实运行核验应分别检查连接、当前加载版本与投递回执；维护操作不应以删除会话、清空历史或反复重启代替排查。

进一步阅读：架构说明、上下文查看器、组件运行契约。