前言¶
在 DeepSeek Harness（DSH）里做智能体开发时，主界面往往是会话列表、工具调用和文件树；长时间盯着同一套 UI，缺少一个「常驻、可对话、又能复用同一套 DSH 能力」的入口。社区里已有以看板娘形态挂在 Web UI 角上的做法；dariodemh/dsh-whale-maid-mascot 在 yefeng7531/dsh-whale-maid-mascot（MIT）基础上扩展，把页面内角色、共享 Agent 会话、本地长期记忆，以及可选的 Telegram 长轮询桥接接到同一条会话上。下面按定位、能力、安装与配置说明如何使用，并交代权限与安全注意点。
这是什么¶
Whale-chan（DeepSeek 娘）是面向 DSH Web UI 的页面内伴侣插件，维护者为 dariodemh，在 SkillHub 目录中归类为「趣味换装」。它不是 DeepSeek 或幻方官方组件；DSH 生态采用「一切皆插件」，社区目录站点与上游无从属关系。插件自述为研究友好的 MIT 开源衍生项目（详见仓库 NOTICE 与 LICENSE），模型供应商与 Telegram Bot 均由使用者自行配置，不会经由此仓库共享。
浏览器角标与 Telegram（若配置）共用同一角色、同一 Agent 会话与同一记忆：手机发的一条消息会进入浏览器里同一段对话，角色在任意一端均可调用 DSH 真实工具（文件、Shell、搜索、Skills 等）。
核心功能¶
页面内（Web UI）¶
- 看板娘：可拖拽、点击互动，四套服装与情绪姿势、 speech bubble。
- 对话：双向可带图片，支持本地生成的卡片与涂鸦类内容。
- Mis trabajos：工作区面板，展示近期文件与预览。
- 长期记忆：偏好称呼、稳定偏好与项目相关事实，默认写入
~/.dsh/whale-maid-mascot/memory.json。 - 其它：主动 check-in、归档聊天、「解释这个术语」等 README 列出的页面能力。
Telegram（可选）¶
- 与页面为同一 DSH Agent 会话（默认 session id 为
whale-maid），可读写文件、执行命令、使用 Skills；回复以单条消息流式编辑方式呈现（streamReplies默认为true）。 - 命令包括：
/new、/status、/memory、/models、/model <provider>/<model>、/stop、/help。 - 配对：Bot 默认忽略所有人；首次需在 Telegram 向 Bot 发送
/pair <code>，配对码由插件写入~/.dsh/whale-maid.pairing.txt。 - 无需公网 IP 或 Webhook：桥接通过 long polling 拉取 Telegram 更新。
- 在你先向 Bot 发过消息后，可收到主动消息（例如长任务结束），符合 Telegram 侧规则。
共享会话与记忆¶
- 打开页面聊天面板时会重载共享 transcript，Telegram 侧消息会出现在页面侧。
- 通过
whale_remember等机制在任一端写入的持久记忆会在另一端可见。
环境与依赖¶
- DeepSeek Harness Desktop 0.2.1-rc.5 或兼容构建（插件为 DSH bundle：宿主侧 + 可选 Web 客户端）。
- DSH 中已配置可用的模型 Provider（与 Profile 现有一致即可）。
- Node：包声明
engines.node为>=20。 - 可选 Telegram：向 @BotFather 申请 Bot Token；当前 package 版本为 2.3.0（以
package.json为准）。
安装与启用¶
推荐从 npm 安装。在 DeepSeek Harness 中打开 Settings → Plugins，安装：
dsh-whale-maid-mascot
重启 DSH 后，Web UI 右下角出现看板娘；Telegram 相关行处于未配置 Token 的空载状态。
本地开发可从 checkout 复制到 ~/.dsh/plugins/dsh-whale-maid-mascot 并在 Profile 的 package.json 中以 file: 依赖与 bundles 引用；README 给出 Windows robocopy 示例，完成后同样需要重启 DSH。本文不展开 clone 流程，以仓库 README 为准。
配置 Telegram¶
- 在 Telegram 与 @BotFather 对话，执行
/newbot，创建 Bot 并复制 Token。 - 将 Token 交给插件，任选其一：
- 写入~/.dsh/whale-maid.token（单行，无其它内容），或
- 启动 DSH 前设置环境变量TELEGRAM_BOT_TOKEN，或
- 在 Profile 的whale-maid-telegram行配置中设置token。 - 重启 DSH；插件生成
~/.dsh/whale-maid.pairing.txt中的配对码。 - 在 Telegram 打开你的 Bot，发送：
/pair <code>
授权完成后可删除配对文件。桥接状态（允许列表、配对码、Telegram offset、共享 session 等）保存在 ~/.dsh/whale-maid.state.json。
可选配置文件¶
可选文件 ~/.dsh/whale-maid.json，或与 Profile cordis.patch.yml 中 whale-maid-telegram 行使用相同键。常用项如下（默认值以 README 表格为准）：
| 键 | 默认 | 含义 |
|---|---|---|
cwd |
~/Documents/deepseek-harness/default-workspace |
共享 Agent 会话的工作目录 |
personaName |
Whale-chan |
角色自称与提示中的名称 |
persona |
— | 完整替换 system prompt |
permissionPreset |
danger-full-access |
会话权限预设 |
sessionId |
whale-maid |
共享会话 id；修改可另开对话 |
model |
profile 默认 | 可为会话固定 { provider, model, reasoningEffort } |
turnTimeoutMs |
900000 |
单轮 Agent 最长等待 |
streamReplies |
true |
Telegram 回复是否流式编辑同一条消息 |
完整键列表见 GitHub README。
典型用法¶
仅页面伴侣：完成 npm 安装并重启后，在右下角与 Whale-chan 对话、换装互动；需要时打开工作区面板查看近期文件。记忆与偏好会落在本地 memory.json，不依赖 Telegram。
页面 + 手机同一脑：配置 Token 并完成 /pair 后，在 Telegram 发送文字或照片；会话与工具调用走真实 DSH session。长任务可在手机端用 /stop；换模型可用 /model <provider>/<model> 或 /models 查看。页面侧再次打开聊天面板即可看到 Telegram 侧消息。
收紧权限：若不希望会话具备完整 Shell 与系统用户级写权限，可在 ~/.dsh/whale-maid.json 将 permissionPreset 设为 workspace-write；部分操作可能等待 DSH 审批，而 Telegram 聊天无法代为点选批准。
架构简述¶
README 中的结构可概括为：浏览器 client.js 经 HTTP 访问宿主 dsh/index.js（看板娘与 /whale-maid-mascot/* 路由）；Telegram 用户经 long poll 与 dsh/telegram.js 通信；二者汇入 dsh/session.js 管理的同一个 DSH Agent 会话（工具、记忆、人设、历史一致）。
适用场景与注意¶
适合：希望在 DSH Web UI 角上保留轻量、可换装的角色伴侣，又希望（可选）用手机延续同一会话并调用真实 Agent 工具的用户；接受 MIT 衍生项目、自行审阅源码的开发者。
务必注意：
- 默认
permissionPreset为danger-full-access：会话内可在你当前 OS 用户权限下执行命令与写文件，这是 Telegram 远程协助能力的基础，也是真实风险。安装前请阅读仓库源码与许可证；更严格隔离可考虑专用 OS 用户、虚拟机，并将cwd指向唯一允许的项目目录。 - Bot Token 为凭证，只应放在本地文件或环境变量，不应写入日志或公开仓库。
- 未授权 Telegram 用户只会收到有限回复；除
/pair与未授权时的/start外，Bot 默认忽略他人。 - 插件以当前 DSH 进程权限运行；趣味换装分类不改变其 Agent 与工具链本质。
结尾¶
dsh-whale-maid-mascot 把页面看板娘、共享 DSH 会话与可选 Telegram 桥接绑在一起：一套记忆、一套工具、两处界面。若要在目录页查看元信息或安装入口，可打开 SkillHub 插件页；实现细节、安全说明与开发命令以 GitHub 仓库 README 为准。
