前言¶
用 qq-bridge 把 QQ（OneBot v11 / SnowLuma）接到 DeepSeek Harness 时，日常改动几乎都落在文件上：人格在 roles/*.md，主动发言和白名单在 config.json，表情含义在 state/stickers.json，素材散在人格卡目录里。改一句人设要开编辑器找路径，调参数要记字段名，上传表情还要自己调 OneBot。下面介绍 Beeasy-L 维护的 dsh-qq-panel：给这套桥接做一个设置面板，可在 DSH 设置页里用，也可以单独起本地网页，只读写 qq-bridge 目录里的文件，不代你启停 SnowLuma 或 QQ 客户端。
这是什么¶
dsh-qq-panel（npm 包名同插件 id）是面向 qq-bridge 的控制面板：人格卡编辑与热切换、表情包与备注管理、主动发言等行为参数、桥接运行状态与日志 tail。维护者 Beeasy-L，许可证 MIT（0.1.1）。插件在激活阶段不读配置、不联网、不抛错；装坏也不会拖垮 Harness 启动。独立形态下用 node server.mjs 监听本机端口，同样界面、零 DSH 插件加载风险。
核心功能¶
面板分四页（插件版与独立网页版同一套 UI）：
| 页 | 能力 |
|---|---|
| 人格卡 | 切换人格、等宽编辑正文；保存前自动备份到 人格卡/<角色>/版本/（保留最近 30 份）；一键启用（热生效）；字符数与红线提醒 |
| 表情包 | 查看文件名、标题、体积、是否已上传；编辑「含义」供 AI 选图；未上传项可一键推进 QQ 收藏表情 |
| 行为参数 | ownerQQ、私聊/群白名单、主动发言（开关/冷场阈值/检查间隔/概率）、唤醒模式、是否允许 AI 潜水、思考强度；保存后需重启桥接才生效 |
| 状态 / 日志 | 桥接在线、当前模式、SnowLuma 连接、当前人格；state/bridge.log 尾部；一键打开桥接控制台 |
未找到 qq-bridge 目录时，会先弹出「填目录」卡片，保存后写入 ~/.dsh/qq-panel.json，下次自动使用。目录解析顺序：环境变量 QQ_BRIDGE_DIR → 上述 json 的 bridgeDir → 与本仓库同级的 qq-bridge/ → 仓库内的 qq-bridge/。
安全边界（README 明确说明）：只读写桥接仓库内文本与图片；控制台令牌不发给前端；上传表情走本机 OneBot HTTP 与 config/onebot_<QQ>.json 令牌；独立网页只监听 127.0.0.1，插件版沿用 DSH 登录态。
安装与启用¶
要求：Node ≥ 22.13、DSH 0.2.x、已有 profile（~/.dsh/profiles/<profile>/）。README 记录的兼容组合包括 DSH 0.2.1-rc.3（Windows 桌面版）、qq-bridge 0.2.1-r1、Node 22.19 / 24.x。
作为 DSH 插件（推荐）：
git clone https://github.com/Beeasy-L/dsh-qq-panel.git dsh-qq-panel
cd dsh-qq-panel
node scripts/install.mjs
默认安装到 desktop profile；Web 端 profile 使用 node scripts/install.mjs --profile=web。
经过上面的步骤后重启 Harness（客户端 bundle 与插件行仅在启动时加载）。入口：设置 → 插件 → dsh-qq-panel。
卸载或启动异常时的救援：
node scripts/uninstall.mjs
node scripts/uninstall.mjs --restore-backup
后者会连同最近一次 package.json 备份一起还原。
独立网页（不加载 DSH 插件）：
node server.mjs
默认 http://127.0.0.1:3101。指定桥接目录与端口示例：
QQ_BRIDGE_DIR=/path/to/qq-bridge node server.mjs 3102
典型用法¶
- 首次打开若提示未配置目录，在卡片里填写 qq-bridge 根路径并保存，或事先设置
QQ_BRIDGE_DIR。 - 在「人格卡」页改文案并保存（自动备份），点启用即可热切换；不必重启桥接。
- 在「行为参数」页改白名单或主动发言后保存，按面板提示重启桥接进程。
- 在「表情包」页补备注；需要上传时确保 SnowLuma 在线且 OneBot HTTP 可达，失败时查看
state/bridge.log。 - 在「状态 / 日志」页确认 SnowLuma 与当前人格，必要时打开桥接控制台。
桥接目录约定（README 图示，兼容旧布局）：
qq-bridge/
├─ roles/<角色>.md
├─ state/current-role.json
├─ state/bridge.log
├─ state/stickers.json
├─ config.json
└─ 人格卡/<角色>/素材/表情包/
└─ ../版本/
旧的 assets/qq-stickers/ 也会被识别为表情素材目录。
适用场景与注意¶
适合已经在用 qq-bridge、又希望少碰原始 JSON/Markdown 路径的 DSH 用户；也适合只想本地管文件、不想动 Harness 插件列表时跑独立 server.mjs。
插件以当前 DSH 进程权限读写你指定的 qq-bridge 目录；安装前请自行查看 GitHub 源码 与 MIT 许可证。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，属社区生态中的第三方插件。
常见排错：装完 Harness 起不来 → node scripts/uninstall.mjs --restore-backup 后再启动；面板未出现 → 确认已重启并在设置 → 插件中找到条目；行为参数无变化 → 重启桥接窗口（与人格卡热生效不同）。
结尾¶
dsh-qq-panel 把 qq-bridge 分散在磁盘上的配置收进一个界面，并补上备份、表情 emoji_id 回写、保存后生效方式提示等细节。需要安装说明与 issue 时见 GitHub 仓库，目录索引见 SkillHub。
