Skip to content
Projects

jiuchai/fish-house has 26 GitHub stars and 3 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 17:17 UTC. Last push 2026-11-13.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

给 AstrBot 的会动的小屋:用画布流程图编排视频节点,聊天时自动切换场景、生成气泡;自带控制台、主题包与主题市场。

Creative & Media

README.md

Original

大肥鱼的小屋

给 AstrBot 用的视频壁纸插件:主题画布上的每个节点就是一段视频,节点怎么连,壁纸就怎么演。

v3.0.2 · AstrBot >= 4.9.0 · Vue 3 + Element Plus 面板 · MIT License


简介

「大肥鱼的小屋」把角色做成一个会活动的视频壁纸:

  • 空闲时在循环节点播放待机视频;
  • 收到消息后按画布连线走到「回消息」节点,等它真正拿起手机,QQ 那边才发回复;
  • 动作节点播完自动沿出边继续,多分支时由模型根据节点说明选择;
  • 节点之间叠化衔接,不会多个视频抢帧;
  • 底部气泡由模型现场生成,3 秒后淡出;
  • 有独立壁纸页,可直接放进 OBS 浏览器源或当桌面壁纸。

整个运行时不依赖内置的固定动作槽位,全部由当前主题的画布驱动。


核心概念

概念 说明
主题 一套完整配置:封面、素材库、画布、设置,打包为一个 .zip
项目 主题的编辑态。每个主题一个项目,素材/封面/画布独立保存
素材库 项目内的视频池,节点只挑素材,不直接绑文件路径
画布节点 一段视频 + 角色类型,节点连成运行时路径
气泡 壁纸底部一句话,由模型生成,默认 3 秒
壁纸页 /fish_house/index.html,不需要登录 AstrBot 就能看

画布驱动是怎么跑的

  1. 收到私聊消息,若当前是循环节点且只有一条出边 → 自动走到下一个节点;
  2. 有多条出边 → 把当前节点、可选出边和每个节点的说明交给模型,要求调用 house_flow_goto 选一条;
  3. 模型只回复没切节点 → 回复发出后兜底走第一条出边,避免卡住;
  4. 一次性节点(动作/过渡)按素材时长播完,自动走第一条出边;phone 节点播一轮后也放下手机继续;
  5. 画布上存在「仅回消息」节点时,回复会等壁纸走到该节点再发(最多等 10 秒,超时照发)。

没有关键词判断、没有固定命令,走哪条路由模型的工具调用决定。

节点类型

类型 行为
循环等待 停在原地等消息,收到后按出边继续
回消息/工作 可回消息、可接任务;空闲一分钟继续
回消息/工作(工作完即走) 同上,任务结束立即继续
仅工作 只接任务;空闲一分钟继续
仅工作(工作完即走) 只接任务,任务结束立即继续
仅回消息 只回复消息;本节点才会真正发 QQ 回复
动作 播一次,按出边继续
过渡 播完按出边继续

画布至少保留一个循环节点,删到最后一个会被阻止。


面板

六个 Tab:

Tab 内容
首页 当前主题大卡、壁纸链接(可复制、可开关底部气泡)、只读画布
主题 本地主题库、导入/导出、应用/刷新、编辑、删除;当前主题标「使用中」
项目 独立素材、封面、画布;保存画布、应用为壁纸
市场 搜索分页、登录/注册、上传/更新、点赞/收藏、下载冲突处理
我的 我发布的、收藏、点赞
设置 叠化时长、手动发/清空气泡、自定义市场地址

画布编辑器

  • 节点拖拽、画布缩放平移,节点卡片显示:名称 / 类型 / 类型说明 / 素材;
  • 从节点右侧圆点拖到目标节点建连线,点节点或连线选中后按 Delete 删除,右键也可删;
  • 删除节点会级联清理相连的边,画布缩放保持不变;
  • 编辑只改本地,点「保存画布」才提交;保存后当前节点立刻同步,不用重新设为当前;
  • 默认选中起点节点,当前播放节点整张卡片高亮;
  • 节点设置里可以写「提示词 / 气泡文案」,作为气泡生成的上下文与兜底文案。

素材

  • 支持多选上传、改名、更换(保留素材 ID)、下载、点击缩略图预览视频;
  • 文件名与展示名分离:落盘用随机 ID,改名只改展示名,不会覆盖其他素材;
  • 正在被节点使用的素材不能删除,会提示是哪个节点在用;
  • 上传按分片进行,大文件也能传。

底部气泡

  • 首页「壁纸链接」卡片里可开关是否显示气泡;
  • 每次进入节点,插件调用当前对话模型现写一句(第一人称、≤12 字),并避开最近用过的 8 句;
  • 显示 3 秒后淡出,出现/消失都是渐隐动画;
  • 模型不可用或超时时,回落到节点的提示词 → 备注 → 节点名;
  • 模型也可以主动调用 house_activity 覆盖当前气泡(可指定停留秒数)。

主题包格式

主题包是一个 .zip(旧 .fishtheme 仍可导入):

theme.json
videos/*.mp4
cover.jpg | cover.png | cover.webp

theme.json 主要字段:

  • meta:id、名称、作者、版本、介绍、封面;
  • config.library:素材库(id、名称、视频、时长);
  • config.flow:画布节点与连线(角色、是否循环、素材、坐标);
  • config.settings:叠化时长;
  • config.actions / videos / audio / durations:旧版兼容字段。

导入时会复制视频、重新分配素材 ID,不会覆盖本地已有文件;应用主题时按素材当前文件重建运行时映射。


主题市场

插件自带市场客户端,默认地址 https://shop.swellengine.com/,可在设置页改成任意自建地址。

  • 邮箱注册,用户名或邮箱登录;
  • 登录态按 AstrBot 用户存在插件后端,刷新页面不用重新登录;
  • 搜索、分页、点赞、收藏、下载量;
  • 上传当前项目,或更新已发布主题(改名、版本、介绍、替换包);
  • 下载撞名时可选:重命名下载 / 覆盖 / 取消。

服务端是独立的 FastAPI + SQLite 项目,源码在 fish-house-theme-server/,支持 Docker 部署,接口见该目录的 README。


壁纸页

http://服务器地址:47613/                     # 控制台(面板)
http://服务器地址:47613/fish_house/index.html # 独立壁纸页
  • 页面首次加载拉一次 state.json / config.json,之后完全靠 WebSocket 推送,不轮询;
  • 视频带声自动播放,被浏览器拦截时回退静音,右上角有声音按钮;
  • 端口没放行就打不开:云服务器要在安全组放行入站 TCP(默认 47613),Windows 要在防火墙加入站规则;从 WebUI 点进插件页时如果连不上,页面会直接提示「端口可能未放行」。
  • 气泡跟随状态推送,超时自动淡出;
  • 断线 3 秒自动重连。

安装

环境要求

  • AstrBot >= 4.9.0;
  • Python 3.10+;
  • 放行插件控制台端口(默认 47613)。

安装插件包

  1. AstrBot 管理面板 →「插件」→ 上传 astrbot_plugin_fish_house.zip;
  2. 或解压到 AstrBot/data/plugins/astrbot_plugin_fish_house/;
  3. 重启 AstrBot;
  4. 打开插件页面(会自动跳到控制台)。

插件页面 /pages/panel/index.html 只是个跳板,真正面板与接口都由插件自己的服务提供。

插件导出包默认不含视频和默认主题(避免包体过大)。新环境装好后需要自己新建主题、上传素材,或从市场下载主题。

从源码安装

cd AstrBot/data/plugins
git clone <仓库地址> astrbot_plugin_fish_house

源码目录里带 assets/default_theme.zip,首次启动(数据目录为空、defaults_applied=0)会自动安装并应用默认主题;已有数据不会被覆盖。


目录结构

astrbot_plugin_fish_house/
├─ main.py                  # 插件入口:消息钩子、LLM 工具、状态恢复
├─ theme_store.py           # 主题包构建/安装/应用
├─ metadata.yaml
├─ _conf_schema.json
├─ core/                    # 常量、配置、状态、流程、存储、主题、内置 Web 服务
├─ api/                     # 面板接口:概览/状态/设置/素材/主题/项目/市场/上传
├─ assets/
│  └─ default_theme.zip     # 内置默认主题(旧 .fishtheme 也兼容)
├─ pages/panel/index.html   # AstrBot 插件页入口(跳转到控制台)
├─ web/panel/               # 面板前端构建产物(npm run build 输出)
├─ web/live/                # 独立壁纸页
├─ frontend/                # 面板源码(Vue 3 + Element Plus)
└─ fish-house-theme-server/ # 主题市场服务端(FastAPI + SQLite)

运行数据:

AstrBot/data/plugin_data/astrbot_plugin_fish_house/
├─ config.json
├─ state.json
├─ videos/
├─ themes/<主题id>/{theme.json,videos,cover.jpg}
├─ uploads/
├─ backups/
└─ market_sessions.json

升级前建议备份整个数据目录。


插件配置

配置 默认 说明
只反馈管理员的对话 关闭 开启后非管理员消息不会触发壁纸动作与回复等待
控制台端口 47613 面板与壁纸页的服务端口,改完需重载插件

LLM 工具

工具 用途
house_flow_goto(node_id) 按画布选择下一个节点(多分支时必需)
house_activity(activity, ttl_seconds) 更新底部气泡,可指定停留秒数

插件会在私聊请求里注入「大肥鱼壁纸」和「流程图」提示,列出节点、当前节点和可选出边。


常见问题

视频不透明?

MP4 不支持透明背景。需要透明壁纸请导入带 alpha 的 WebM。

浏览器没有声音?

浏览器会拦截带声自动播放,页面先回退静音,点右上角声音按钮即可恢复。

改了没生效?

  • 面板前端:Ctrl+F5 强刷;
  • Python 代码或路由:重启 AstrBot;
  • 改过控制台端口:记得放行新端口,并用新地址打开。

壁纸不动 / 卡在某个节点?

  • 检查当前主题是否至少有一个循环节点;
  • 检查节点是否绑定了素材,素材文件是否还在;
  • 卡在「回消息」节点时,发一条新消息即可继续。

气泡不显示?

  • 首页「壁纸链接」卡片里确认气泡开关已打开;
  • 气泡只在 3 秒内显示,可用设置页「活动气泡」手动发一条测试。

刷新后要重新登录市场?

登录 token 按 AstrBot 用户名存在插件后端,正常刷新不需要重登;换了市场地址则旧 token 失效。

市场连不上?

  1. 设置页市场地址需以 http:// 或 https:// 开头;
  2. 确认服务端已部署、HTTPS 证书有效;
  3. 自建市场请对照 fish-house-theme-server/README.md 检查反向代理。

安全说明

  • 市场密码用 PBKDF2-HMAC-SHA256(20 万次迭代 + 随机盐)存储,不可逆;
  • 市场 token 服务端只存 SHA-256 摘要,30 天过期;
  • 主题包校验文件数量、体积、路径与文件白名单,拒绝 ../ 穿越;
  • 插件端不保存市场密码,但浏览器 localStorage 与 market_sessions.json 中的 token 为明文,机器多人共用时建议缩短有效期或改用独立账号。

开发

# 面板前端(Vue 3 + Element Plus)
cd frontend
npm install
npm run build          # 输出到 web/panel

# 主题市场服务端
cd fish-house-theme-server
python -m pip install -r requirements.txt
python app.py          # 或 docker compose up -d --build

前端构建后把 web/panel 同步到插件目录,重启 AstrBot 或强刷页面即可。


更新日志

v3.0.2

  • 继续优化画布逻辑:节点切换严格沿连线路径走,不跳节点;从循环节点切出时等当前动画播到首尾衔接点再切,不打断动画。
  • 修复路径相关 bug:回复只在壁纸走到「回消息」节点后发出;手动切换节点后清理残留的游走/待切状态,模型能正确感知当前节点;壁纸页改用 WebSocket 推送、不再轮询状态。

v3.0.1

  • 优化面板的 Vue 结构:状态与接口调用集中到 store,页面按 views / components / dialogs 分层,组件只负责渲染。
  • 修复无法修改控制台端口的问题:插件启动时把实际端口写入 pages/panel/port.json,WebUI 插件页据此跳转,改端口后重载插件即可;连不上时会提示对应端口可能未放行。

License

MIT License © 2026 jiuchai