jiuchai/fish-house
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.
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 & MediaREADME.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 就能看 |
画布驱动是怎么跑的
- 收到私聊消息,若当前是循环节点且只有一条出边 → 自动走到下一个节点;
- 有多条出边 → 把当前节点、可选出边和每个节点的说明交给模型,要求调用
house_flow_goto选一条; - 模型只回复没切节点 → 回复发出后兜底走第一条出边,避免卡住;
- 一次性节点(动作/过渡)按素材时长播完,自动走第一条出边;
phone节点播一轮后也放下手机继续; - 画布上存在「仅回消息」节点时,回复会等壁纸走到该节点再发(最多等 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)。
安装插件包
- AstrBot 管理面板 →「插件」→ 上传
astrbot_plugin_fish_house.zip; - 或解压到
AstrBot/data/plugins/astrbot_plugin_fish_house/; - 重启 AstrBot;
- 打开插件页面(会自动跳到控制台)。
插件页面 /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 失效。
市场连不上?
- 设置页市场地址需以
http://或https://开头; - 确认服务端已部署、HTTPS 证书有效;
- 自建市场请对照
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