dsh-qqbot-yuro 🐳

Yuro 拟人化 QQ 群聊机器人插件 —— 基于 DeepSeek Harness（DSH）qqbot 通道的 cordis 插件。

为 QQ 群聊 bot 注入拟人化生活感：情绪 / 作息 / 精力 / 成员画像 / 兴趣过滤 / 预算 / 识图 / 下载 / 技能自进化 等一整套能力。

本插件不含任何运行时的个人数据（人设、画像、记忆、密钥均不在仓库内，部署后由机器人自行积累）。

---

🧭 架构：插件能做什么 vs 需要 patch

探明上游 @tencent-connect/dsh-qqbot（v0.4.0）后，其第三方扩展面如下：

能力面	官方 API	本插件承载
工具（识图/下载/预算/作息/群睡/精力/生日/文件）	✅ ctx.tools.register	✅ tools/ + scripts/
技能自管理（yuro-* 技能 list/read/write/remove）	✅ ctx.tools	✅ tools/skill.js
persona 提示词注入	✅ systemPrompt.section	✅ index.js（内置默认人设 + 可覆盖）
入站对话机制（斜杠指令/兴趣过滤/作息睡眠门控/成员画像/主动消息）	❌ 无扩展点	⚠️ 需 patches/ 配套 patch
出站格式化（占位提示/思考摘要/markdown 降级/回复延迟）	❌ 需 bot 实例，不可注入	⚠️ 需 patches/ 配套 patch

为什么：上游 im-qqbot 插件把消息入站 bot.on('message') 与出站 bot 实例全部封装在插件内部，inject 仅暴露 agents，不注册消息事件、不提供中间件注册点。第三方插件无法经官方 API 拦截入站消息或拿到发送实例。因此入站/出站机制由仓库 patches/ 目录的 patch 提供，插件本体通过官方 API 承载工具/技能/人设。

---

📦 目录结构

dsh-qqbot-yuro/
├── index.js           # cordis 插件入口（tools + skill + persona）
├── config.js          # 配置项
├── package.json
├── tools/             # 工具定义层（defs/spawn/skill）
│   ├── defs.js        #   8 个脚本工具注册
│   ├── spawn.js       #   python 安全调用封装（argv 白名单 + 配置注入）
│   └── skill.js       #   yuro-* 技能自管理工具
├── scripts/           # python 实现层（配置驱动，无硬编码路径）
│   ├── yuro_layers.py #   数据目录/网关解析（读插件注入的环境变量）
│   ├── yuro_budget.py #   每日 token 预算 + 精力联动 + 睡眠
│   ├── yuro_routine.py#   生活作息状态机
│   ├── yuro_group_sleep.py  # 单群临时睡眠
│   ├── yuro_group_energy.py # 群精力曲线
│   ├── yuro_image_describe.py # 图片识别（含反查）
│   ├── yuro_birthday.py #  群友生日祝福
│   ├── yuro_download.py #  下载到工作区
│   └── yuro_file_tools.py # 文件查看/搜索/转码
├── patches/           # 入站+出站机制 patch（配合 dsh-qqbot 使用）
│   └── dsh-qqbot-yuro.patch
└── skills/            # 群聊技能模板（可部署到 ~/.dsh/skills）
    ├── comfyui-image-gen/
    ├── sticker-sender/
    ├── yuro-download/
    ├── yuro-file-ops/
    └── yuro-self-evolve/

---

🚀 安装

前置

• Node.js ≥ 20，pnpm
• DeepSeek Harness（npm install -g @deepseek-ai/dsh）
• QQ 开放平台机器人账号 + @tencent-connect/dsh-qqbot 插件已装
• 可用的 LLM 网关（默认 http://127.0.0.1:18081/v1，OpenAI 兼容）

步骤

# 1. 添加插件
npx -p @deepseek-ai/dsh dsh plugin --profile qqbot add github:<your>/dsh-qqbot-yuro

# 2. 在 profile 的 cordis.patch.yml 挂载
#    - insert:
#        - id: dsh-qqbot-yuro
#          name: dsh-qqbot-yuro
#          config:
#            botName: yuro
#            workDir: work-qq-group
#            llmBaseUrl: http://127.0.0.1:18081/v1
#            model: <MODEL>

# 3. 应用入站/出站 patch（见 patches/README）

---

⚙️ 配置

配置项	默认	说明
botName	yuro	机器人名（影响 --bot 注入与内置人设）
pythonPath	python	python 可执行名/路径
workDir	work-qq-group	群聊工作区目录名（相对 ~/.dsh/）
llmBaseUrl	http://127.0.0.1:18081/v1	LLM 网关（兴趣/识图/预算/反思共用）
model	<MODEL>	群聊默认模型名（必填）
personaFile	内置默认	可选：外部人设文件绝对路径
skillsDir	无	可选：yuro-* 技能目录

脚本环境变量（由插件注入，脚本层读取，实现配置驱动）：

• YURO_WORK_DIR — 工作区目录名
• YURO_LLM_BASE_URL — LLM 网关
• YURO_MODEL — 模型名
• YURO_NEWAPI_DB — 可选：new-api 计费库路径（未配置则预算脚本跳过）

---

🛠️ 能力

工具（插件经官方 API 注册）

工具	说明
yuro_download	下载 http/https 到工作区
yuro_file_tools	工作区文件 info/head/tail/grep/count/convert
yuro_image_describe	图片识别（full/lite/缓存）
yuro_budget	今日 token 预算报告
yuro_routine	生活作息查看/切换
yuro_group_sleep	单群临时睡眠
yuro_group_energy	群精力查询
yuro_birthday	生日检查/列表
yuro_skill	yuro-* 技能自管理

Persona（内置拟人化人设）

• 内置默认人设（情绪/作息/性格/边界），可 personaFile 覆盖
• 热更新重载（文件 mtime 感知）

入站/出站机制（patch 提供）

• 斜杠指令、兴趣过滤、作息睡眠门控、成员画像、主动消息、占位提示、markdown 降级

---

🤝 贡献

欢迎 Issue / PR。请注意：

1. 不提交任何真实密钥 / openid / 个人路径（仓库保持占位符约定）
2. commit message 用中性表述，不出现隐私相关术语
3. 涉及上游扩展点的能力，欢迎向上游 tencent-connect/dsh-qqbot 提 PR（当前最大诉求：暴露消息中间件注册点，让入站机制可插件化）

---

📄 License

MIT。

---

📍 仓库定位（Yuro / Yume 项目族）

本项目的代码与文档分散在 5 个仓库，各自职责边界如下：

仓库	职责	可见性
yuro_yume	项目正本：理念、规格、研究文档	私有
y2-runtime	「推倒重做」后的运行时底座与最小骨架	私有
yuro-bot	功能与插件代码快照（不含人设与数据）	私有
dsh-qqbot-yuro	对外发布的 DSH QQ 插件形态	公开
dsh-tool-yuro	工具层插件：脚本收敛为 ctx.tools	私有

本仓库定位：对外发布的插件形态：本族中唯一公开的仓库，以 DSH cordis 插件形式发布 Yuro 的能力（含 patches/ skills/ tools/）。