猫猫 · Maomao for DSH

猫猫是一个适用于 DeepSeek Harness（DSH） 的开源聊天伙伴插件。你可以在 DSH 里直接和猫猫聊天，也可以把自己的 QQ、Telegram 或 Lark / 飞书机器人接进同一个控制面板。

• 桌面聊天：新建会话时选择「猫猫」预设，即可使用内置人格和独立的本地记忆。
• 聊天平台：在面板里接入自己的 Bot、绑定会话，再验证首条回复。私聊和群聊都可以用。
• 按需扩展：单独配置模型、记忆、人格、媒体与主动分享。基础文字聊天可以跟随 DSH 默认模型。

---

快速开始

1. 安装

目前验证的 DSH 版本为 0.2.2-rc.2，插件接受 DSH 0.2.x（不低于 0.2.2-rc.1）；DSH 0.3 发布后需要重新验证。请先在 DSH 的模型设置中准备一个可用的对话模型。使用外部渠道的记忆和分享功能时，还需要系统可调用的 Python 3；表情包需要 Pillow。

在桌面端打开「插件 → 安装第三方插件」，输入 maomao-dsh-panel@0.2.28，安装后按提示重启。也可以下载并导入 .tgz 安装包。GitHub Releases

Web 版可以用 DSH 命令行从 npm 安装固定版本。npm 包

dsh plugin --profile web add maomao-dsh-panel@0.2.28

也可以从 GitHub 安装同一个版本。

dsh plugin --profile web add 'github:ififi2017/dsh-plugin-maomao#v0.2.28'

2. 在 DSH 里聊天

重启后打开「设置 → 猫猫 → 总览」。只在 DSH 聊天的话，直接在新会话的模式菜单选「猫猫」，发一句「猫猫你好」。

3. 接入一个聊天平台

先选一个平台走通 连接 Bot → 绑定会话 → 验证第一条回复。面板会分别显示连接、配对和测试消息的处理进度。

渠道	准备什么	怎么绑定
Lark / 飞书	选对 Lark 或飞书版本，扫码创建应用，或导入已有 App ID 和 App Secret。应用需启用机器人能力和长连接事件，并发布版本	在目标私聊发配对指令，把 Bot 回的确认码填回面板
Telegram	在 BotFather 创建 Bot，将 Token 填到面板。已有开启管理模式的 Bot 也可以扫码创建	打开配对链接点 Start，或在私聊发配对指令，再填确认码
QQ	扫码授权或导入 App ID 和 App Secret。先确认同一个 Bot 只由一个实例连接	选择群或私聊。群内先 @Bot，再发送配对指令，最后填确认码

绑定后进入「测试回复」，点「生成测试消息」，把带编号的整句发到选定会话（QQ 群内需要 @Bot）。面板会显示同一条消息的收件、模型和投递结果。

4. 平台权限清单

• Lark / 飞书：订阅 im.message.receive_v1，开通 im:message.p2p_msg:readonly（私聊）和 im:message:send_as_bot（发消息）。要在群里 @ 猫猫，再开 im:message.group_at_msg:readonly；读图和发图需要 im:resource 与 im:message:readonly；回复时显示「正在输入」的表情回应需要消息表情回复权限，没有时只是不显示。扫码创建的新应用会自动申请私聊、群聊和图片权限；之前扫码创建的应用需要到开放平台手动添加群权限。改完权限或事件后都要发布新版本。
• Telegram：要在群里 @ 猫猫，必须在 @BotFather 发 /setprivacy → 选择 Bot → Disable，然后把 Bot 移出群再重新拉入。默认开启的隐私模式下，群里普通的 @ 消息不会转给 Bot。关闭后猫猫仍然只回应 @ 她或回复她的消息。
• QQ：群聊接话依赖 QQ 平台的消息接收设置；Markdown 和按钮需要平台开通，未开通时自动改发纯文字。

5. 出问题时先看哪里

「诊断」页按平台显示收件、模型、投递和媒体下载的最近结果；「API 报错」长期保存平台和模型接口报错；「终端」实时显示本次运行的调试日志（见下文「诊断与日志」）。群聊没有回应时，「渠道与会话 → 会话与权限 → 群聊」会直接写出卡在哪一步。

---

日常使用

面板地图

面板	能做什么
总览	查看渠道在线和绑定情况，进入常用配置；首次使用可按接入顺序操作
渠道与会话	按平台管理「连接 Bot」「会话与权限」「测试回复」；飞书和 Telegram 在「会话与权限」里管理群聊
人设	「会话分配」设置默认与每个会话的角色；「角色库」查看内置猫猫设定或编辑自定义角色
模型与能力	分别配置对话、识图、生图、语音、向量检索、联网与浏览器以及服务凭据
记忆	「自主学习」查看与修正学到的内容；「表情库」浏览和移除收藏的表情；「范围与共享」控制隔离与共享；「向量索引」重建检索
主动互动	「QQ 群接话」管理接话轮数与暂停；「私聊主动分享」管理寂寞小猫、后台浏览、目标、免打扰与试跑
诊断	按平台查最近处理结果，查看「API 报错」和实时「终端」日志

未保存的修改会在所属页面和分栏标记；切页或关闭设置面板仍可继续编辑，重启 DSH 前需保存。

QQ 群

绑定 QQ 群后，可在「主动互动 → QQ 群接话」按群开启。模型会根据群消息、最近的群聊上下文和同群记忆判断是否接话，以及用什么方式接：一句短话、一个表情包，或正常回一两句。

• 和其他机器人斗嘴时，只有一个人在看的情况下最多接 2 轮；最近 5 分钟有至少两个人说话时，才按面板设置的轮数（1–5）。
• 群友可发送 /停止互动 暂停，已绑定的群主人可发送 /恢复互动，也可以在面板里暂停或恢复。自然语言的“这轮先停一下”只结束当轮互动。
• 模型可以用 qq_group_query 查询群资料和成员列表；这些接口受 QQ 平台权限限制，查不到时继续用群聊上下文。
• 群内主人身份与“允许这个群聊天”分开：在「添加绑定 → 绑定 QQ 群或私聊」选择「QQ群主人身份」，由本人在目标群 @机器人发送 /pair 配对码，再把确认码填回面板。不凭群主或管理员职位认主。

飞书 / Lark 与 Telegram 群聊（开发版）

把 Bot 拉进群后（先按上面的权限清单设置好），由已绑定的主人在群里 @猫猫 一次，这个群就会开启；之后群里任何人 @ 猫猫或回复她的消息，她都会接话。未开启的群里，其他人的 @ 会被忽略。

• 每个群有独立的会话、自主学习和表情库，不使用主人的私聊记忆，也不会收到主动分享。主人会被认出来，其他人用固定的「群友 xxxx」标记区分；学到的内容记在说话的人名下。
• 猫猫只回应 @ 她或回复她的消息，不会像 QQ 群那样主动接话。
• 「渠道与会话 → 会话与权限 → 群聊」显示已开启的群和每个平台的检查结果（隐私模式、Bot 身份、最近一次收到的群消息、没有回应的原因），可以单独关闭或重新开启某个群。在面板关闭的群，主人再 @ 也不会自动开启。配置 groups.enabled: false 可整体关闭群聊。

QQ 私聊与配对

「渠道与会话 → QQ → 会话与权限 → QQ 私聊」可设置 接受陌生人私聊，默认关闭。关闭时只接受已配对或配置在 dmAllowlist 的用户；其他人会收到限频的配对提示，仍可使用 /sid 查询自己的 QQ OpenID、/pair 查看步骤。开启后未配对用户也能直接聊天，会消耗模型额度，但不会获得主人身份。

配对：「会话与权限 → 添加绑定 → 绑定 QQ 群或私聊」选择「QQ 私聊」→ 生成指令 → 私聊 Bot 发送完整 /pair 配对码 → 将收到的确认码填回面板。已经绑定了飞书或 Telegram 主人时，可以在配对时选择「关联到主人」：这个 QQ 私聊会被认作同一位主人，与飞书 / Telegram 共用私聊学习记忆（惦记的事、日记、档案等）；不关联则保持独立记忆。重新配对时不选主人即可取消关联。QQ 群不受影响，仍按群独立。新配对成功后，猫猫会用当前对话模型和人设发一条简短招呼，之后可以直接接着聊。

私聊主动分享

在「主动互动 → 私聊主动分享」选择目标私聊和模式。「模拟运行」只生成不发送；「定时发送」需要勾选确认后保存，确认只对所选的那个私聊有效，换目标需要重新确认。寂寞小猫的问候由对话模型根据时间、惦记的事和最近的日记现写，没有合适的话时可以不发；模型不可用时才退回固定短句。免打扰、每日上限和未回复后的逐步退让仍然有效。寂寞小猫只从选定的这一个私聊找你，不会几个渠道同时发；你在飞书、Telegram 或已关联主人的 QQ 私聊里说话，都算作在聊天，计时会重新开始，「晚安」也会在所有渠道生效。

表情库

猫猫在聊天里看到可复用、不含隐私的表情时会自己判断是否收藏，之后按语气挑着发，也可以只发一个表情不配文字。「记忆 → 表情库」按聊天列出收藏：缩略图、描述、适合的场合和最近发送时间。移除某张表情会删除图片并记住它的指纹，之后在聊天里再看到也不会被重新收藏。收藏需要可用的识图能力（见「看图与模型」）。

---

进阶功能与原理

自主学习

在「设置 → 猫猫 → 记忆 → 自主学习」管理，默认开启，可单独关闭回复后的后台总结。

猫猫在普通聊天中自行判断哪些内容值得记住，不需要固定口令：

类型	记什么
档案 profile	对方稳定的喜好、习惯和背景
经历 episode	一起经历过的事
惦记的事 followup	对方提到、还没结果的事（考试、面试、出行……），时机到了顺口问起，有结果后更新
猫猫日记 diary	猫猫自己的第一人称小日记，只写真实发生的聊天和读到的东西，之后聊天和主动问候时会自然提起
语气 style / 梗 meme	这里的人怎么说话、怎么接梗；不熟的梗先查资料再决定记不记
技能 skill	有适用条件、步骤和检查方法的经验，下次相关任务先加载再用

• 工具：maomao_memory（查询、记录、修正、遗忘）、maomao_skill（技能）、maomao_meme（查梗，复用 DSH 联网搜索，保留来源）、maomao_stickers（看图、收藏、搜索、发送表情）。
• 记在谁名下由程序决定：每条记录的对象由宿主按当前发言者确定，原话依据必须出自这个人的发言，模型无法把记忆记到别人名下。每轮注入的记忆目录会标出「当前发言者」与「其他人」，避免在群里认错人。
• 写入需要原话依据，修正带版本检查；过期和遗忘的内容不再召回。面板可查看依据、使用次数、编辑、遗忘、恢复最近 20 个版本，并导出 MEMORY.md 或 SKILL.md。
• 普通回复成功后，后台用当前对话模型总结（默认每个范围每天最多 40 次，合计 200 次，会额外消耗模型额度）。失败不影响聊天。
• 学习数据存放在 $DSH_HOME/integrations/maomao-learning/，每个范围独立 SQLite 文件：桌面、每个 QQ 群和私聊、每个飞书 / Telegram 群分别隔离；飞书和 Telegram 私聊只有关联同一主人并开启共享后才共用。

拟人化设计

目标是相处起来自然，而不是让人误以为对面是真人：被认真问到时，猫猫会如实说明自己是 AI。

• 人设写的是“她是谁”：喜恶、主见、可以不接话、会惦记别人的事，而不是输出配额。
• 说话节奏提醒：猫猫最近几句如果都用「喵」或 emoji 收尾、都是感叹号、频繁写括号动作或颜文字、开头总一样，下一句会收到一行只针对这一句的提醒。
• 对话会定期换新：QQ 群和私聊满 40 轮或 12 小时换一次模型会话，接话判断器每 8 次换一次，避免模型模仿自己大量的旧回复；连续性由最近的群消息、记忆和日记承接。固定说明放在系统提示里，不随每条消息重复存入历史。
• 少一点“表单感”：对话选项只在需要从几个具体方案里挑一个时才用，同一个聊天用过一次后至少隔 8 条回复、15 分钟才会再提供。
• 出错时说人话：工具、图片或查询失败时用一句自己的话带过，不说状态码、权限、后台这类词。
• 正在输入：Telegram 显示“正在输入”，飞书在你的消息上加一个「敲键盘」表情回应并在回复后移除，QQ 私聊显示输入状态（QQ 群不支持）。多段回复之间按字数停顿一下。

模型可直接调用的聊天工具

QQ、Lark / 飞书、Telegram 使用同一套工具接口。对话模型根据当前请求和上下文自行选择工具，无须固定关键词；工具只对当前授权会话有效。参数写错时工具会告诉模型怎么改，而不是笼统地拒绝。

工具	功能	配置
maomao_generate_image	生成或编辑图片并投递	模型与能力 → 生图
maomao_speak	合成并发送语音，尊重“只用文字”	模型与能力 → 语音
maomao_web_search / maomao_web_fetch	查公共资讯、阅读公开网页，附来源	复用 DSH 的联网提供商
maomao_browser_*	打开、读取、跟随链接、截图动态网页	独立的 Chrome / Edge 环境
maomao_project_read / maomao_reference_image	读取公开 GitHub 项目的设定、提示词和原图，作为生图参考；支持直接粘贴 tree / blob 链接	只支持公开仓库
qq_group_query	查询当前 QQ 群及成员的公开资料	QQ 平台权限

每轮最多发送一份生成媒体，搜索/网页读取最多三次，浏览器最多操作四次，项目文件读取最多十次、参考图最多三张（每张不超过 5 MB）。工具报告真实投递状态，不确定时不自动重试。不向渠道模型开放终端、文件访问或任意收件人参数。

联网与浏览器

联网搜索单独配置。 DSH 当前默认的搜索提供商是 DeepSeek；把聊天模型设为 Google 或 OpenAI，不会自动把搜索也切过去。请在 DSH 的「插件 → 内置插件设置 → 联网搜索」检查提供商和凭据。猫猫面板的「模型与能力 → 联网与浏览器」可保存 DeepSeek 搜索凭据（复用 DEEPSEEK_API_KEY）、测试搜索、开关浏览器并试读一个公开页面。

浏览器基于 Playwright，优先使用本机的 Chrome / Edge；首次调用才启动，每轮聊天使用独立的临时环境，结束后清理。只读公开 HTTPS 网页，不连接个人浏览器、不读取 Cookie、不操作表单。网络出口会校验 DNS 并拒绝内网地址；本机 TUN 代理返回的 198.18.0.0/15 Fake-IP 会用 HTTPS DNS 重新查询真实地址再校验。

看图与模型

• 对话模型能看图时，图片直接交给它看（QQ 和飞书 / Telegram 都是），少一次调用、少一个失败点。「模型与能力 → 识图」会提示当前对话模型是否支持看图，并推荐「跟随对话模型」：表情收藏也用它，不需要单独的识图模型和密钥。
• 识图列表包含 DSH 中所有支持图片输入的已配置模型，以及 Google / OpenAI 直连模型。
• QQ 图片下载会跟随 QQ 自己域名的跳转，网络错误或超时自动重试一次。有人先连发几张图再单独提问时，会附上同一个人最近 2 分钟内的最后 3 张图。
• 飞书 / Lark 使用富文本发送 Markdown；QQ 优先使用原生 Markdown，平台明确拒绝时回退为纯文本（群里不附编号选项）。
• Lark / 飞书与 Telegram 的语音会在本机用支持 libopus 的 FFmpeg 转为 Opus 后发送。

诊断与日志

• API 报错：平台和模型接口的报错（QQ 拒绝 Markdown、图片下载失败、Telegram / 飞书接口错误、模型调用失败等）长期保存，最多 90 天、2000 条，可在「诊断 → API 报错」查看和清空。
• 终端：「诊断 → 终端」实时显示本次运行的调试日志，分为错误、警告、信息、调试、追踪五级，可按级别、来源和关键字筛选。内容包括每轮对话、工具调用的参数和结果（记忆、技能、表情、联网、生图、语音）、接话判断、后台总结、会话轮换和群消息被忽略的原因。
• 滚动日志只保存本次启动后的最近 24 小时，重启 DSH 后清空；记录级别可在终端里调整。日志保存在 $DSH_HOME/integrations/maomao-logs/，只有本机可读，密钥和令牌会被遮盖。

数据与隐私

凭据由 DSH 凭据库管理。记忆、绑定、表情库和日志保存在运行实例的本地目录。聊天、图片或向量请求会按配置发给所选模型服务；搜索只发送必要的公共关键词。公开源码只包含通用配置和合成测试资料。

---

欢迎二次开发

欢迎提出改进建议、提交 PR，或 Fork 后扩展人格、渠道和设置界面。开发需要 Node.js >=24.9、Python 3、用于图片测试的 Pillow，以及支持 libopus 的 FFmpeg。

git clone https://github.com/ififi2017/dsh-plugin-maomao.git
cd dsh-plugin-maomao
npm ci --ignore-scripts
npm test
npm run pack:release

scripts/humanlike-report.mjs 可以对一份对话记录（dialogue.sqlite3 或 JSONL）统计机器人式的说话习惯。

• 贡献指南有源码入口、隔离测试方法和发版步骤。
• DSH 官方 bundle 发布文档介绍了清单、patch 和安装方式。
• 代码采用 MIT 许可证。猫猫形象和宣传图见素材说明。

这是社区插件，由 fi_niaR Studio 维护。