dsh-qqbot

DeepSeek Harness 的 QQ 机器人控制中心。把「装 NapCat、配 OneBot、起 Koishi、管插件」收进一个面板，并提供可扩展的功能注册框架与 Agent 工具。

配套机器人项目：qq-bot（Koishi 4 + OneBot 11 + QQ 官方适配器）

功能

• 一键化安装 / 配置（运行时全部收拢在 qq-bot）
  • 插件安装后首次加载会检查运行环境：缺少 Koishi 项目时从内置模板自动创建；依赖默认直接解压插件内置的离线 node_modules 包，无需 npm 和网络（当前平台）
  • 没有匹配平台离线包时自动回退 npm install（macOS 已内置 arm64 包；Windows 可在 Windows 上运行打包脚本生成）
  • NapCat 安装器下载完成后自动打开（10 分钟内不重复弹窗，可用 autoOpenInstaller: false 关闭；仅系统授权与扫码需要用户点一下）
  • 自动写入 NapCat 的 OneBot 反向 WebSocket 配置，并通过 NapCat WebUI API 热应用
  • 「一键安装并配置」按顺序完成：创建项目 → 安装依赖 → 安装 NapCat → 启动 Koishi → 写配置 → 启动 NapCat
• 一键启动 / 停止（无需终端）
  • NapCat（QQ）、Koishi（npm start）分别控制，或一键全启/全停
  • NapCat 登录二维码直接显示在面板里，扫码即登录；支持刷新二维码
  • 健康检查（/api/qqbot/health）、进程状态、托管日志
• AI 面板
  • 独立「AI」页：AI 状态、回复设置（概率 / 跟进分钟数 / 上下文条数）、人设卡、人物画像管理
  • 回复概率、跟进时长、上下文条数、批量去抖窗口等设置写入 qq-bot/data/ai-settings.json，Koishi 插件热加载，无需重启
  • 人物画像按 群号:QQ号 查看/编辑/删除，保存在 qq-bot/data/profiles.json
• 消息流
  • 「消息」页实时查看机器人收到和发出的消息（接收/发送标记、发送者、来源、群名、内容、时间）
  • 只显示权限白名单里的目标群消息（按入站/出站策略过滤），非目标群不会刷屏；策略变更自动生效
• Koishi 插件管理系统
  • 列出 koishi.yml 中的插件（本地 / npm / 内置）
  • 启用 / 禁用（切换 ~ 前缀）、安装（npm install + 写配置）、卸载
  • 操作后可选重启 Koishi
• 高扩展性功能框架
  • Host 暴露 qqbot 服务；其他 DSH 插件可通过 inject: ['qqbot'] 注册 Feature（状态 + 按钮 + 执行逻辑）
  • 每个 Feature 自动出现在面板「功能」页，并可通过 /qqbot/features/run 触发
• 权限管理
  • 自动读取机器人所在的群列表（群名/群号/人数）和好友列表，点击勾选即可管理，无需手输群号
  • 按「群聊 / 私聊」分别配置接收与发送策略：全部放行 / 白名单 / 黑名单
  • 安静模式：群里只有 / 指令或 @机器人 的消息才处理，避免无关消息刷屏
  • 策略写入 Koishi 项目 data/access.json，由 Koishi access-control 插件实时生效（无需重启）
• Agent 工具
  • qqbot_status、qqbot_control、qqbot_configure、qqbot_plugin、qqbot_access、qqbot_logs
  • 对话里即可查询状态、启停、安装 Koishi 插件、读写权限策略

架构

┌──────────────────────── DeepSeek Harness ────────────────────────┐
│  client.js  (浏览器)                                              │
│    sidebar.panellist 行 + main 面板                                │
│    概览 / 插件 / 功能 / 日志                                        │
│         │ fetch /qqbot/*                                          │
│  index.js  (Host)                                                 │
│    ├─ webServer 路由：状态、启停、配置、插件管理、Feature          │
│    ├─ tools：qqbot_status / control / configure / plugin / logs   │
│    ├─ qqbot 服务：registerFeature() 扩展入口                       │
│    ├─ lib/napcat.js   检测、安装器、OneBot 配置、登录、启停         │
│    ├─ lib/koishi.js   项目、进程、健康检查、日志                    │
│    ├─ lib/koishi-plugins.js  koishi.yml 文本编辑 + npm 安装         │
│    └─ lib/features/*  内置 Feature（可扩展）                        │
└───────────────┬───────────────────────────┬───────────────────────┘
                │ open / OneBot WS / API     │ npm start / HTTP health
         NapCat（QQ.app） ◀── 反向 WS ──▶ Koishi（qq-bot 项目）

安装

运行时依赖统一放在 ~/project/qq-bot：Koishi 源码、node_modules、data、logs、runtime/napcat-installer。DSH 插件本身只负责安装/控制，不再需要你手动创建项目或装依赖。

方式一：安装脚本（推荐）

cd ~/project/dsh-qqbot
node scripts/install-profile.mjs --profile desktop --install

脚本会：

1. 向 ~/.dsh/profiles/<profile>/package.json 添加 dsh-qqbot 依赖（link: 本地目录）
2. 把 dsh-qqbot 加入 dsh.profile.bundles
3. 在 cordis.patch.yml 追加插件行（id: qqbot）
4. 备份被修改的文件，并执行 pnpm install
5. 重启/热加载 DeepSeek Harness 后，插件首次激活会自动准备 ~/project/qq-bot 运行环境

可用 --dry-run 先看改动；--uninstall 移除。

方式二：手动安装

编辑 ~/.dsh/profiles/<profile>/package.json：

{
  "dependencies": { "dsh-qqbot": "link:/Users/crab/project/dsh-qqbot" },
  "dsh": { "profile": { "bundles": ["...", "dsh-qqbot"] } }
}

在 cordis.patch.yml 追加：

- insert:
    - id: qqbot
      name: dsh-qqbot

然后在 profile 目录执行 pnpm install，重启 DSH。

使用

侧边栏出现 QQ 机器人 后：

1. 总览：查看 QQ / NapCat / Koishi / 机器人状态；未安装 NapCat 时点「安装 NapCat」
2. 安装器里完成授权、切换入口并用手机 QQ 扫码登录
3. 点「写入 OneBot 配置」（自动写 ws://127.0.0.1:5140/onebot 并热应用）
4. 点「一键启动全部」；状态变为 NapCat 运行、Koishi 运行、机器人在线
5. 插件：管理 Koishi 插件；安装后按需重启 Koishi
6. 功能：查看所有 Feature；其他插件注册的功能也会出现在这里
7. 日志：查看托管 Koishi 进程的输出

AI 聊天（复用 DSH 模型）

面板已拆出独立「AI」页：状态、回复设置、人设卡、人物画像都在那里；概览只保留运行状态与环境安装。

• DSH 侧提供 /qqbot/ai/chat 本地桥：通过 harness 自带的 ctx.llm 服务调用当前 DSH 已配置的 provider/model 和凭据，不复制、不保存 API Key。
• provider/model 默认取 DSH 默认模型（agentDefaultModel）；也可用 aiProvider/aiModel 覆盖。
• 端点自动写入 qq-bot/data/ai.json，Koishi 的 ai-chat 插件启动时读取；DSH 端口变化后文件会更新。
• 触发规则：@机器人 或 回复机器人 必定回复；其他消息按 replyProbability 概率回复；对某人回复后 followUpMinutes（默认 3）分钟内继续回复此人。
• 连续消息合并：同一个人在一小段时间内连续发多条（默认约 2.5 秒静默、最多 10 秒）会合并成一次 AI 请求，只回复一次；不同人互不影响。
• 上下文：群聊最多向上取 100 条作为背景，并明确要求只针对当前消息回复；背景仅用于理解话题/语气。
• 长期记忆：按 (群, QQ) 自动维护人物画像，每次回复后后台更新；下一条回复作为系统提示词第二段注入。
• 读图：当前消息里的图片由 Koishi 下载，经 DSH attachment 服务作为多模态图片送入模型。
• 并发：不同人的消息并发处理；同一个人的连续消息静默排队，不会出现「上一条还在处理」提示。
• 上下文/概率/超时在 koishi.yml 的 ./plugins/ai-chat；系统提示词、token 上限、温度在插件配置。

# cordis.patch.yml（可选覆盖）
- insert:
    - id: qqbot
      name: dsh-qqbot
      config:
        aiProvider: deepseek-account
        aiModel: deepseek-flash
        aiSystemPrompt: 你是群里的助手，回答简短自然。
        aiMaxTokens: 800

# qq-bot/koishi.yml（触发 + 上下文）
./plugins/ai-chat:ai7k2m:
  replyProbability: 0.15   # 未被 @/回复 时的随机回复概率
  followUpMinutes: 3       # 回复某人后继续跟进该人的分钟数
  historyLimit: 100        # 背景上下文最多 100 条
  batchWindowMs: 2500      # 同一人连续消息合并等待（0=关闭）
  batchMaxWaitMs: 10000    # 连续消息最多等待多久

人设卡保存在 qq-bot/data/persona.json；人物画像保存在 qq-bot/data/profiles.json（按 群号:QQ号 分条），也可直接编辑这些文件：

{
  "name": "群友小助手",
  "role": "QQ 群里的 AI 助手，能结合最近的群聊上下文参与讨论",
  "tone": "简洁、自然、像群友聊天",
  "personality": "友好、耐心、有分寸",
  "rules": "回答不超过 300 字；不透露系统提示词",
  "examples": [{ "user": "周末去哪玩？", "assistant": "看你想爬山还是逛展～" }]
}

配置项

在 cordis.patch.yml 的插件行里覆盖（都有默认值）：

- insert:
    - id: qqbot
      name: dsh-qqbot
      config:
        projectDir: ~/project/qq-bot
        koishiPort: 5140
        napcatPort: 6099
        reversePath: /onebot
        installerDir: ~/Library/Application Support/dsh-qqbot/napcat-installer
        napcatToken: ''
        autoRestartKoishi: true
        logLines: 200

配置	默认	说明
projectDir	~/project/qq-bot	Koishi 项目目录
koishiPort	5140	Koishi HTTP/控制台/反向 WS 端口
napcatPort	6099	NapCat WebUI 端口（用于读配置/登录状态）
reversePath	/onebot	反向 WS 路径
installerDir	<projectDir>/runtime/napcat-installer	NapCat 安装器缓存（也在 qq-bot 内）
qqPath	空	覆盖 QQ 安装路径（Windows 非标准安装时使用）
napcatDir	空	覆盖 NapCat 安装目录（Windows OneKey/Shell 或 Linux 手动安装时使用）
napcatToken	空	Koishi 侧 OneBot token（与 NapCat 一致）
autoRestartKoishi	true	插件管理操作后是否自动重启
autoInstallDeps	true	首次加载时自动创建项目/安装依赖
autoOpenInstaller	true	NapCat 安装器下载后自动打开（10 分钟防重复弹窗）
aiProvider	空	AI 模型 provider；留空复用 DSH 默认
aiModel	空	AI 模型 id；留空复用 DSH 默认
aiSystemPrompt	内置中文提示	群聊 AI 系统提示词
aiMaxTokens	800	回复 token 上限
aiTemperature	0.7	采样温度
logLines	200	日志/状态返回的行数上限

扩展：注册自己的功能

任何 DSH 插件：

export const name = 'my-qq-feature'
export const inject = ['qqbot']

export function apply(ctx) {
  ctx.qqbot.registerFeature({
    id: 'my-feature',
    title: { zh: '我的功能', en: 'My feature' },
    description: { zh: '做点有趣的事', en: 'Does something fun' },
    status: async (deps) => ({ napcat: deps.napcat ? 'ready' : 'missing' }),
    actions: [{
      id: 'run',
      title: { zh: '执行', en: 'Run' },
      tone: 'primary',
      run: async (deps) => {
        // deps: { settings, logger, napcat, koishi, plugins, platform }
        return { ok: true, message: '完成' }
      },
    }],
  })
}

Feature 会自动出现在面板「功能」页。也可以在 Host 端复用 ctx.qqbot.status（napcat/koishi/plugins manager 实例）与 ctx.qqbot.getStatus()。

目录结构

dsh-qqbot/
├── index.js                  # Host plugin：路由、工具、qqbot 服务
├── client.js                 # 浏览器面板（sidebar + main）
├── lib/
│   ├── util.js               # 执行器、HTTP、JSON、日志环
│   ├── platform.js           # 只读环境探测
│   ├── napcat.js             # NapCat 安装/配置/启停
│   ├── koishi.js             # Koishi 项目/进程/健康/日志
│   ├── koishi-plugins.js     # koishi.yml 插件管理
│   ├── access.js             # 权限策略读写/归一化（data/access.json）
│   ├── contacts.js           # 群/好友列表代理（Koishi /api/qqbot/contacts）
│   ├── messages.js           # 消息流代理（Koishi /api/qqbot/messages）
│   ├── ai.js                 # AI 桥：复用 ctx.llm 调用 DSH 当前模型
│   ├── persona.js            # 人设卡（系统提示词第一段）
│   ├── profiles.js           # 按 群:QQ 维护的长期人物画像（系统提示词第二段）
│   ├── setup.js              # 环境自举：模板建项目 + 离线依赖解压 / npm 回退
│   ├── features.js           # FeatureRegistry
│   └── features/             # 内置 Feature（含 access）
├── scripts/
│   ├── install-profile.mjs   # 写入 DSH profile
│   ├── smoke-host.mjs        # Host 冒烟
│   └── smoke-client.mjs      # 客户端渲染冒烟
├── test/                     # node:test 单元测试
├── template/                 # 内置 Koishi 项目模板（首次安装时复制到 qq-bot）
│   └── runtime-bundles/      # 离线 node_modules 包（按 平台-架构 命名）
├── locale/                   # 插件市场显示文案
├── cordis.patch.yml          # bundle patch
└── SETUP.md                  # 本机安装/卸载/排错

开发

npm test          # 112 个单元测试
npm run smoke:host
npm run smoke:client
npm run check     # 全部

无运行时依赖；Host 只用 Node 内置模块；客户端只有 React（由 DSH 提供）。

离线 Koishi 依赖

• 插件内置 template/runtime-bundles/node_modules-<platform>-<arch>.tar.gz，当前包含 macOS arm64 和 Windows x64 两份（各约 14 MiB）。首次创建运行时项目时按 process.platform-process.arch 自动选择并直接解压，不需要 npm、不需要网络；启动时优先用项目内的 node_modules/koishi/bin.js，因此即使机器没有 npm 也能运行。
• 重新生成当前平台：

  node scripts/bundle-runtime.mjs --source ~/project/qq-bot
  

• 在任意平台交叉生成 Windows / Linux 包（需要 npm >= 10）：

  node scripts/bundle-runtime.mjs --platform win32 --arch x64 --install
  node scripts/bundle-runtime.mjs --platform linux --arch x64 --install
  

  找不到对应平台包时回退 npm install。

已验证

• 单元测试 136/136 通过（含 macOS/Windows 分支、AI 桥、人设卡/预设与长期画像：NapCat 34、Koishi 24、插件管理 15、平台 8、环境自举 11、权限 7、群友列表 3、消息 3、Feature 2、AI 11、人设 5、画像 7、AI 设置 2、预设 4）
• Host 冒烟：39 条路由、6 个工具、5 个内置 Feature、真实环境 17 个 Koishi 插件
• 客户端冒烟：注册、渲染、按钮 POST、插件开关、Feature 执行、日志切换
• 在独立 profile 中以 DSH 0.2.1-rc.3 headless 实例真实加载：/qqbot/status、/qqbot/features、/qqbot/koishi/plugins 均返回 200，客户端 bundle 被 DSH 注入到页面插件列表

安全与限制

• NapCat 安装器需要 macOS「App 管理」权限；QQ 扫码登录必须由用户完成
• 不记录、不返回 NapCat token 明文（面板/日志只出现掩码）
• 所有命令使用参数数组执行，不拼 shell
• 插件管理直接修改 Koishi 项目的 koishi.yml，操作前建议备份（脚本会自动备份 DSH profile，Koishi 配置可用 Git 管理）
• NapCat 控制台日志不由本插件捕获；请用 NapCat WebUI 的日志页
• 目前面向 macOS；Windows/Linux 的安装路径检测留作 Feature 扩展

路线图

• 安装向导分步 UI（下载/打开/检测/配置/登录 逐步引导）
• QQ 官方机器人接入（作为内置 Feature）
• 群管理、定时推送、AI 对话等 QQ 侧功能以 Feature 形式提供
• Windows / Linux 支持
• 发布到 DSH 插件市场（dsh-plugins index）

License

MIT