前言¶
在 DSH 里跑智能体时，常见做法是另开终端维护一套 Python 机器人：改 config.yaml、查日志、手动启停进程。微信 UI 自动化、本地 ASR、GPU 歌声合成仍应留在机器人侧；若用 TypeScript 全量重写，成本高且容易丢掉 GPU 能力。下面介绍社区插件 dsh-we-whalegirl（维护者 gzyy111）：在 DSH 内提供 Host + Client 控制面，负责进程托管、同源代理、设置页与 whalegirl_* Agent 工具，不替代机器人本体。
这是什么¶
dsh-we-whalegirl 是 DeepSeek Harness（DSH）上的工作流类插件（当前版本 0.1.0，插件代码 MIT 许可）。它是控制面：拉起/停止机器人进程、把浏览器请求代理到本机 HTTP API、注册 9 个 Agent 工具，并在 设置 → 鲸鱼娘 提供完整设置页。不是机器人本体——微信 UI 自动化、faster-whisper、edge-tts、SoulX-Singer / ACE-Step（conda + GPU）等仍由 Python 侧承担，插件不包含也不重写它们。
社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装前请自行阅读源码与许可证。插件以当前 DSH 进程权限运行。
核心功能¶
进程与代理¶
Host 半边通过 supervisor 用 subprocess 拉起机器人目录中的 web_main.py。启动序列固定为：热激活微信 UIA → 起 web 服务 → 连微信。支持启动、停止、重启；重启前会检查队列，避免打断在途回复。
同源代理将 /dsh-we-whalegirl/* 转发到 127.0.0.1:<port>/api/*，设置页通过 fetch 访问同源 API，无需处理 CORS。
功能开关与人设¶
设置页可管理 22 项功能开关，涵盖聊天核心、媒体与表情包、点歌三级后端、算命五术数、笑话、开机补消息、频率参数等。功能开关以机器人侧 config.yaml 为单一真源，插件不复制一份状态；多数开关需要重启机器人才生效（handler 在启动时一次性注入），人设保存则是例外。
人设支持显示名、描述、提示词、温度、token 上限、示例对话；保存即热更新，不重启、不重连微信，并提供「锁定出厂人设」开关。
回复频率与平台¶
回复频率提供三档预设（安静 / 正常 / 话痨）及 12 项细调，并区分「@ 必回」与「概率参与」。
平台相关包括微信通道控制、监听群列表，以及 QQ 开放平台凭证（Secret 由机器人本体 Fernet 加密）。另有语音与点歌（音色 / 音调 / 语速、真唱音色版本、混音配比、三级后端开关）、模型与高级（AI 接口、日志级别、读取日志尾、清空上下文、插件自身配置只读展示）。
Agent 工具与可选面板¶
注册 9 个工具：whalegirl_status、whalegirl_start、whalegirl_stop、whalegirl_restart、whalegirl_say、whalegirl_image、whalegirl_cover、whalegirl_divination、whalegirl_config。可在 DSH 对话里用这些工具指挥机器人。
配置项 enablePanel: true 时，侧栏会出现「鲸鱼娘」总览（统计、能力自检、消息流、日志）。
安装与启用¶
从 GitHub 安装（推荐）¶
dsh plugin --profile web add github:gzyy111/dsh-we-whalegirl
本地目录安装¶
dsh plugin --profile web add /path/to/dsh-we-whalegirl
也可在 DSH 桌面版「插件」页用本地安装入口指向插件目录。安装完成后重启一次 DSH（bundle 层需重启才会组装）。
必填配置¶
在 profile 的 cordis.patch.yml 中补全 botRoot，否则点击「启动」会提示未配置：
- id: whalegirl
name: dsh-we-whalegirl
config:
botRoot: 'D:/bots/deepseekgirl' # 含 web_main.py 的目录
pythonExe: '' # 留空 = <botRoot>\.venv\Scripts\python.exe
port: 8080
mode: auto # auto | attach | manual
autoStart: false
stopOnExit: false
allowAnyRoom: false
automaticRestart: false
enablePanel: false
机器人本体需满足：
- Windows + 已登录的微信桌面版（UI 自动化，窗口不能最小化）
- 机器人目录内有
.venv\Scripts\python.exe与web_main.py - 机器人 HTTP API 只监听
127.0.0.1:<port>
本插件依赖机器人提供的 /api/settings*、/api/style*、/api/capabilities、/api/divination。若使用上游原版 linxisama/deepseekgirl，需先补齐这些接口（设置页依赖它们）。
典型用法¶
工作方式概览¶
DSH Desktop ── Host 插件 ──┬─ supervisor：subprocess 拉起 web_main.py
├─ 同源代理：/dsh-we-whalegirl/* → 127.0.0.1:8080/api/*
└─ 9 个 whalegirl_* 工具
浏览器页面（设置 → 鲸鱼娘）──fetch──> /dsh-we-whalegirl/api/*（同源，无 CORS）
日常可在 设置 → 鲸鱼娘 启停进程、改人设与频率、开关能力；在 Agent 对话中调用 whalegirl_status 查看状态，或用 whalegirl_say 等工具下发动作。需要仪表盘时，将 enablePanel 设为 true 并重启 DSH 后使用侧栏总览。
插件自有日志路径：%USERPROFILE%\.dsh\dsh-we-whalegirl\plugin.log（2 MB 轮转）。
适用场景与注意¶
适合：已在 Windows 上自建微信/QQ「鲸鱼娘」类 Python 机器人（含 web_main.py 与本地 venv），希望在 DSH 内统一启停、改配置，并通过 whalegirl_* 在对话里操作，而不把微信自动化与 GPU 歌声合成搬进插件。
注意：
- 微信通道依赖桌面 UI 自动化，机器人须在交互式桌面会话中运行。
- 曲库、表情包、模型权重在机器人侧，插件不含这些资源。
- 设置页字段白名单由机器人侧
settings_api.py决定。 - 设计原则包括：失效不拖垮宿主（Promise catch、代理与页面错误边界、注册失败降级）。
结尾¶
dsh-we-whalegirl 把自建「鲸鱼娘」机器人的运维收敛到 DSH：进程托管、22 项开关、人设热更新、频率与平台配置，以及 9 个 whalegirl_* 工具。机器人能力仍留在 Python 侧，插件只做控制面。
