Install Guide

安装使用

魔丸自带公益初始接口，安装后可以先体验基础 AI 能力。稳定使用时，再进入控制台换成自己的 API，并按需启用 Agent 工作台与群管理。

Quick Start

从安装到打开控制台

在 Yunzai 根目录安装，启动 Bot 后查看控制台打印里的登录口令。内置 ZCode 运行时需要宿主 Node ≥ 22，版本不足时仍可使用 OpenCode 后端。

首次启动

安装依赖后重启 Bot。第一次打开控制台时，按控制台打印里的登录口令进入后台。

确认插件位于 `plugins/crystelf-plugin`。
运行 `pnpm install` 或 `npm install`。
重启 Bot，让插件加载。
使用 ZCode 后端时，宿主 Node 需 ≥ 22。

配置接口与模型

公益初始接口用于跑通基础体验，稳定使用建议换成自己的接口。

在 API 设置配置主对话、生图、图片监控和搜索接口。
主对话兼容 OpenAI 与 Anthropic 协议，可接入自定义供应商。
生图可选 OpenAI、火山 Agent Plan、SenseNova、SD WebUI 或即梦。

按需开启能力

群管理、图片监控、Agent 写入和自动处理默认关闭，建议逐步开启。

先选一个测试群开启群管理，观察日志后再启用自动动作。
Agent 工作台默认关闭，需要时再开启只读分析或受控写入。
危险操作前确认 Bot 权限与群规则。

Commands

常用群命令

插件命令统一以 `#灵晶` 开头（与官网品牌名「魔丸」不同）。Agent、巡检和运维命令通常需要主人权限。

核心

#灵晶帮助默认帮助，可加 AI / 管理 / 娱乐 / 调试分类

#灵晶状态获取 Bot 运行状态图

#灵晶查看更新日志查看插件更新记录

#更新灵晶拉取插件更新

#强制更新灵晶丢弃本地修改并覆盖为远端版本

群管理与运营

#灵晶开启群管理开启本群群管理能力

#灵晶关闭群管理关闭本群群管理能力

#群总结获取本群总结

#申请头衔你的头衔提交群头衔申请

#头衔申请列表查看待审核头衔

#同意头衔编号审核通过并发放头衔

#拒绝头衔编号理由拒绝头衔申请

#取消头衔申请取消自己的头衔申请

Agent 与巡检（主人）

#zcode 任务派发完整 Agent 任务

#zcode只读任务只读分析档，不改文件不联网

#切换agentOpenCode 与 ZCode 后端共享切换

#zcode会话 / 状态 / 停止查看、切换、中断任务

#zcode回滚两步确认撤销最近写入任务

#zcode新会话清空上下文，开启新会话

#巡检列表 / #开启巡检查看和添加定时巡检

#关闭巡检编号 / #立即巡检删除或立即执行巡检

生图

自然语言生图例如“生成一张花海图片”

#灵晶改图要求携带或回复图片修改单张图

#灵晶融合要求至少两张、最多 14 张参考图融合

运维

#灵晶健康报告完整体检报告

#灵晶备份列表 / #灵晶立即备份查看或立即执行配置备份

#灵晶任务查看定时任务一览

#灵晶水位查看磁盘 / 内存 / Redis 水位

#灵晶晨报 / #灵晶发晨报预览或立即发送运维晨报

#查看进程 / #杀死PID查看进程列表与结束指定进程

#灵晶重启二次确认后重启 Bot