# hl-ai-plugin **Repository Path**: fox-glaze/hl-ai-plugin ## Basic Information - **Project Name**: hl-ai-plugin - **Description**: ai对话 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-23 - **Last Updated**: 2026-09-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

HL-AI-Plugin

Yunzai AI 对话插件 —— 多模型渠道 · 上下文管理 · 预设人格 · 伪人 · MCP 工具调用 · 识图

node yunzai license

--- ## 这个版本改了什么 本插件基于 [chatai-plugin](https://github.com/XxxXTeam/chatai-plugin) 移植，功能保持一致，**换掉了会让服务器崩的地基，并补上了工具调用的安全边界**： | 改动 | 原因 | |------|------| | **数据库：`better-sqlite3` → Node 内置 `node:sqlite`** | `better-sqlite3` 需要 node-gyp 本地编译。服务器缺编译链、或升级 Node 后 ABI 不匹配，就会报"二进制损坏 / 编译失败"，`pnpm i` 装完一重启就崩。换成内置模块后**零安装、零编译、零二进制**，这类崩溃从根上消失。 | | **Web 面板默认共享 Yunzai 端口** | 不再额外占用 3000 端口，也不用单独开防火墙。 | | **Redis 复用 Yunzai 全局连接** | 去掉 `ioredis` 依赖，不再多开一条 Redis 连接。 | | **精简依赖** | 删掉 6 个没有任何代码引用的依赖（`@napi-rs/canvas`、`tesseract.js`、`markmap-lib`、`vectra`、`ioredis`、`better-sqlite3`），并复用 Yunzai 根目录已装的 `express` / `yaml` / `ws` 等。 | | **去掉遥测上报** | 不再向外部服务器上报启动信息。 | | **Agent 化：工具协议提示词** | 原版只有 `ChatAgent` 里写了工具指引，而实际走的是 `ChatService` —— 模型拿到 255 个工具却没有任何调用纪律。抽成共用模块，MCP 工具排最前，明确"先扫清单再决定路径"。 | | **权限收口：本地文件系统锁主人** | 原版 `read_file` / `list_directory` 任何群员都能调，而路径限制只挡 `/etc`、`C:\Windows`，不限制在 Yunzai 目录内 —— 一句「读一下 config/config.yaml」就能拿到 API Key。15 个涉及本地文件、进程、环境的工具改为 `requireMaster`。 | | **修复 `requireMaster` 一直失效** | `McpManager.getTools()` 重建工具对象时漏掉了权限元数据，导致工具定义里写的 `requireMaster` 到不了过滤器。`execute_command` 从原版起就标了这个字段，一直没生效。 | | **超危险操作二次确认** | 风险分级只看工具名，`execute_command` 里 `ls -la` 和 `rm -rf /var/lib` 待遇相同。新增看**参数内容**的判定，分「绝对禁止」和「必须逐次确认」两级。 | | **高风险操作转交主人审批** | 原版是"谁触发谁批准"，群管理员自己就能放行踢人、写文件。现在非主人触发 high 风险时私聊推给主人，`yolo` 和「允许本对话」都绕不过。 | | **工具确认能真正确认** | 原版只认光秃秃的「确认」三字，`#确认` 会被 `#` 命令检查提前丢弃；且待确认项的归属 key 在登记侧和回复侧算法不一致，回复永远匹配不上，只能等超时。 | > **识图 / OCR 走视觉模型**，不装本地 OCR 引擎 —— 配一个支持视觉的模型（如 `gpt-4o`、`gemini-2.0-flash`、`claude-sonnet-4`）即可。 --- ## ⚠️ 环境要求 | 依赖 | 要求 | 说明 | |------|------|------| | **Node.js** | **>= 23.4** | **硬性要求**，见下方说明 | | Yunzai-Bot | V3 | TRSS-Yunzai / Miao-Yunzai | | pnpm | >= 8 | Yunzai 自带 | | Redis | 可选 | 复用 Yunzai 的连接，不需额外配置 | ### 为什么要 Node 23.4+ 插件用 Node 内置的 `node:sqlite` 存数据。这个模块的可用性分三档： | Node 版本 | 情况 | |-----------|------| | < 22.5 | 没有这个模块，**不可用** | | 22.5 ~ 23.3 | 有，但需要 `--experimental-sqlite` 启动参数，得改 `config/pm2.yaml` | | **>= 23.4** | **免参数直接可用** ← 本插件要求 | 推荐用 **LTS 24.x**。版本不够时插件会在启动阶段直接给出中文提示，而不是丢一个难定位的崩溃。 检查版本： ```bash node -v ``` --- ## 📦 安装 在 **Yunzai 根目录** 执行： - gitee ```bash git clone --depth=1 https://gitee.com/fox-glaze/hl-ai-plugin.git ./plugins/hl-ai-plugin pnpm install ``` - gitcode 更新较慢 仓库为gitee的镜像 12小时推送一次 ```bash git clone --depth=1 https://gitcode.com/sujier/hl-ai-plugin.git ./plugins/hl-ai-plugin pnpm install ``` **不需要** `pnpm approve-builds`，也不需要 Visual Studio Build Tools / python3 / node-gyp —— 本插件没有需要编译的原生依赖。 然后重启 Yunzai： ```bash node app ``` --- ## 🚀 开始用 ### 1. 配置模型渠道 渠道列表、预设人格、MCP 服务器这类结构化数据都在 Web 面板里管理： ``` #ai管理面板 获取临时登录链接（5 分钟有效） #ai管理面板 永久 获取永久链接 ``` 首次进入会有引导向导：选渠道 → 填 API Key → 测试连接 → 选模型 → 选人格 → 配触发方式。 ### 2. 开始对话 | 方式 | 示例 | |------|------| | @机器人 | `@Bot 你好` | | 前缀触发 | `#chat 你好` | | 私聊 | 直接发消息 | --- ## 📖 命令 > 命令前缀默认 `#ai`，可在 Web 面板或 `config/config.yaml` 里改
对话管理 | 命令 | 说明 | |------|------| | `#结束对话` | 结束当前对话，清空上下文 | | `#对话状态` | 查看当前对话状态 | | `#清除记忆` | 清除个人记忆 | | `#我的记忆` | 查看已保存的记忆 | | `#总结记忆` | 整理合并记忆条目 |
人格设定 | 命令 | 说明 | 权限 | |------|------|------| | `#ai设置人格 <内容>` | 设置个人人格 | 所有人 | | `#ai查看人格` | 查看当前生效人格 | 所有人 | | `#ai清除人格` | 清除个人人格 | 所有人 | | `#ai设置群人格 <内容>` | 设置群人格 | 群管理 | | `#ai清除群人格` | 清除群人格 | 群管理 | 人格优先级：`群内用户设置 > 群组设置 > 用户全局设置 > 默认预设`
工具 / Agent 控制 插件把模型当 Agent 用：收到请求先扫可用工具（**MCP 优先**），没有对应工具才走其他路径。工具调用纪律（不编造结果、写操作前先读、破坏性操作先确认）由运行时注入的工作协议约束。 | 命令 | 说明 | 权限 | |------|------|------| | `#工具模式` | 查看当前确认模式 | 所有人 | | `#工具模式 auto` | 低风险自动执行，中高风险要确认（默认） | 群管理 | | `#工具模式 confirm_all` | 所有工具都要确认 | 群管理 | | `#工具模式 ask` | 完全不向模型暴露工具 | 群管理 | | `#工具模式 yolo` | 跳过确认，保留硬拦截 | 主人 | | `#危险工具 状态` | 查看高危工具开关 | 主人 | | `#危险工具 开启` | 放开写文件 / 删文件 / 群管理等 16 个高危工具 | 主人 | **回应确认请求**：收到「检测到模型请求执行工具」后回复 | 回复 | 效果 | |------|------| | `确认` `确定` `同意` `ok` `y` `1` | 执行本次 | | `取消` `拒绝` `算了` `n` `2` | 不执行 | | `允许本对话` | 本对话内同类工具不再询问 | 都可带 `#` 前缀，群里也可 `@Bot 确认`。默认 60 秒内有效，多条待确认时可用 `确认工具 <编号>` 指定。 ### 权限模型 分三档，从严到宽： **① 服务器本地文件系统、进程与环境信息 —— 仅 Bot 主人。** 以下 15 个工具带 `requireMaster`，非主人（含群主、管理员）在工具列表阶段就看不到，模型无从调用： ``` read_file write_file list_directory get_file_info create_directory delete_file copy_file move_file download_to_file download_group_file_to_file execute_command read_env get_system_info get_process_info get_environment ``` 写类工具（`write_file` / `delete_file` / `move_file` / `copy_file` / `create_directory` / `execute_command`）还额外受 `builtinTools.allowDangerous` 管，默认关闭，需 `#危险工具 开启`。 **② 群文件的增删改 —— 群管理员及以上。** 以下 6 个工具带 `requiredPermission: 'admin'`，普通群员看不到；群主、群管理员、主人都能用： ``` upload_group_file delete_group_file delete_group_folder create_group_folder move_group_file rename_group_file ``` 只读类（`get_group_files`、`get_file_url`、`get_group_file_system_info` 等）不受限制，群员仍可用。 **③ 群管理操作（踢人 / 禁言 / 改群名等）** 受 `dangerousTools` 名单 + `master` 门槛管辖。 ### 确认层级 权限决定"能不能调用"，确认决定"调用前要不要问"。两者独立： | 层级 | 谁来确认 | 能否跳过 | 覆盖范围 | |------|------|------|------| | **绝对禁止** | 不问，直接拒 | — | `rm -rf /`、`mkfs`、`dd of=/dev/sda`、fork bomb、`format c:` | | **超危险** | 非主人转交主人；主人自己批 | `yolo` / 会话免确认都**跳不过** | `rm -rf 某目录`、`git reset --hard`、`DROP DATABASE`、`FLUSHALL`、`curl \| sh`、改 `.env` / `config.yaml` / `node_modules` | | **必确认** | 发起者自己批（权限已把住） | 同上，**跳不过** | `delete_group_file`、`delete_group_folder`、`delete_group_notice`、`recall_message` | | **高风险** | 非主人转交主人；主人自己批 | 主人可用 `yolo` 跳过 | 群管理操作、写文件等 | | 中风险 | 发起者自己批 | 可用「允许本对话」 | 发消息、读网页、存记忆 | | 低风险 | `auto` 模式不问 | — | 查时间、搜索、查群信息 | **「必确认」是给不可逆操作留的保险。** 删群文件的权限门槛已经把住了（能调的是群管理员及以上），所以不必惊动主人 —— 但删除没法撤销，即使主人开了 `yolo`、即使刚点过「允许本对话」，每次删之前都会再问一遍： ``` ⚠️ 不可逆操作待确认 ━━━━━━━━━━━━━━ 发起者：张管理(888777) 来源：群 测试群(12345) 模型：gemini-2.5-flash 原始请求：把群里那个 abc123 文件删掉 ━━━━━━━━━━━━━━ 请求执行 1 个工具： [1] delete_group_file　（不可逆 · 风险 medium） 作用：删除群文件。需群管理员及以上权限，执行前会要求确认。 来源：内置工具 参数： group_id: 12345 file_id: abc123 ━━━━━━━━━━━━━━ 删除后无法恢复，请确认目标无误。 回复：确认 / 取消 （可带 # 前缀，也可回复 y / n；60 秒内有效；不支持会话免确认） 编号 2341836a｜多条待确认时回复「确认工具 2341836a」 ``` 超危险与高风险的通知格式相同，转交主人时额外注明"发起者无法自行批准"，并给 3 分钟决定时间。 ### 超危险规则表 内置 40 余条命令规则 + 9 条敏感路径规则，覆盖删除、磁盘、权限、进程、包管理、Git、数据库、远程执行、敏感文件九类。判定看的是**参数内容**，且扫描所有工具的参数（MCP 工具名不可预测，`run_sql`、`db_exec` 都可能真的执行），但跳过 `message` / `prompt` / `query` 这类自然语言字段 —— 聊天里提到 `rm -rf` 不会误报。 规则可在安全设置页追加或按名字停用，**默认表始终生效**，追加不会顶掉它。 ### 配置入口 结构化配置在**工具安全设置页**（`#ai管理面板` 会给出直达链接，或登录后访问 `/chatai/security/`）： | 分组 | 内容 | |---|---| | 总开关 | 启用内置工具、放开高危工具 | | 确认模式 | 默认模式、超时、会话免确认及其风险上限 | | 主人审批 | 高风险转交开关、**审批推送目标 QQ**（留空用 Yunzai 主人配置） | | 超危险操作 | 检测开关、是否必须主人批、超时、停用规则、追加命令/路径规则 | | 必确认工具 | 追加必确认工具、停用默认必确认项 | | 风险等级覆盖 | 强制高/中/低风险、免确认白名单 | | 工具启用范围 | 白名单、黑名单、危险工具名单 | > 主面板（Next.js）的字段列表是编译进产物的，新增配置项不会自动出现在那里，所以安全相关的 24 个字段集中放在这个手写页面，走同一套 API 和 JWT 鉴权。
绘图 / 识图 / 语音 | 命令 | 说明 | |------|------| | `#ai画图 <描述>` | 生成图片 | | `#ai编辑图片 <描述>` | 编辑图片（需引用图片） | | `#ai看图 <问题>` | 识图问答（需引用图片） | | `#ai语音 <内容>` | 文字转语音 |
群聊功能 | 命令 | 说明 | |------|------| | `#群聊总结` | AI 总结近期群聊 | | `#个人画像` / `#画像@xxx` | 用户画像分析 | | `#今日词云` | 群聊词云图 | | `#群记忆` | 查看群共享记忆 |
群管理 / 主人命令 群管理： | 命令 | 说明 | |------|------| | `#群管理面板` | 获取群设置面板链接 | | `#ai群设置` | 查看本群功能状态 | | `#ai群伪人开启/关闭` | 开关本群伪人 | | `#ai群绘图开启/关闭` | 开关本群绘图 | 主人： | 命令 | 说明 | |------|------| | `#ai状态` | 插件运行状态 | | `#ai调试开启/关闭` | 全局调试模式 | | `#ai伪人开启/关闭` | 全局伪人模式 | | `#ai设置模型 <名称>` | 设置默认模型 | | `#ai结束全部对话` | 清空所有对话历史 | | `#ai更新` / `#ai强制更新` | 更新插件 | | `#ai帮助` | 命令帮助 |
--- ## ✨ 功能 | 功能 | 说明 | |------|------| | 🤖 **多模型** | OpenAI、Claude、Gemini，以及所有兼容 OpenAI 格式的服务（DeepSeek、通义千问、智谱、Moonshot、OpenRouter、Ollama、LM Studio…） | | 🔌 **第三方中转站** | 自动规范化 baseUrl（补 `/v1`、识别自定义路径），支持多地址 + 多 APIKey 轮询、负载均衡、故障转移 | | 🔧 **MCP 工具调用** | 内置 22 类工具，支持 MCP 协议四种传输：`npm` / `stdio` / `SSE` / `HTTP`，可自定义扩展 | | 🤖 **Agent 模式** | 选工具时 MCP 优先，支持多工具组合完成任务；工具执行按风险分级确认（`#工具模式`） | | 💬 **上下文管理** | 多轮记忆、双限控制（条数 + Token）、超长自动总结压缩、群 / 私聊隔离 | | 🧠 **长期记忆** | 自动提取关键信息、用户画像、群共享记忆 | | 🎭 **预设人格** | 角色预设、四级人格覆盖、动态变量替换 | | 🤝 **伪人模式** | 按概率自然参与群聊，可配触发条件与独立模型 | | 📢 **主动聊天** | 基于群活跃度触发，支持静默时段 | | 👁️ **识图 / OCR** | 走视觉模型，无需本地 OCR 引擎 | | 🎨 **AI 绘图** | 图像生成与编辑 | | 🎙️ **语音合成** | GPT-SoVITS、Fish-Audio、Edge-TTS | | 📊 **使用统计** | API 调用、模型排行、工具调用、Token 消耗 | | 🌐 **Web 配置面板** | 共享 Yunzai 端口，渠道 / 预设 / MCP / 群设置全可视化 | --- ## 🛠️ 自定义工具与 MCP 把 JS 文件丢进 `data/tools/` 目录，重启即自动加载： ```javascript // data/tools/hello.js export default { name: 'my_hello', function: { name: 'my_hello', description: '向指定用户打招呼。AI 会根据这段描述决定何时调用，写清楚点', parameters: { type: 'object', properties: { name: { type: 'string', description: '要打招呼的人名' } }, required: ['name'] } }, async run(args, context) { const e = context.getEvent() // 当前消息事件 const bot = context.getBot() // 机器人实例 return { success: true, message: `你好，${args.name}！` } } } ``` 外部 MCP 服务器写在 `data/mcp-servers.json`，或在 Web 面板的「MCP 服务器」页添加： ```json { "servers": { "filesystem": { "type": "npm", "package": "@anthropic/mcp-server-filesystem", "args": ["/home/user/documents"] } } } ``` > 📖 **完整开发流程**（参数定义、上下文 API、返回格式、权限校验、四种 MCP 传输的服务端实现、调试方法、开发模板）见 **[docs/TOOLS.md](docs/TOOLS.md)** --- ## 🔄 更新 ```bash # 命令更新（推荐） #ai更新 # 手动更新 cd plugins/hl-ai-plugin git pull cd ../.. pnpm install ``` --- ## ❓ 常见问题
启动报错：无法加载 Node 内置模块 node:sqlite Node 版本不够。运行 `node -v` 查看： - 低于 22.5：没有这个模块 - 22.5 ~ 23.3：需要 `--experimental-sqlite` 启动参数 **解决**：升级 Node 到 **23.4 或更高**（推荐 LTS 24.x），重启即可。 用 nvm 的话： ```bash nvm install 24 nvm use 24 ``` 升级 Node 后**不需要**重装依赖 —— 本插件没有绑定 ABI 的原生模块。
AI 不回复 1. `#ai管理面板` 进面板，确认已添加有效渠道 2. 渠道管理里点「测试连接」 3. 检查触发方式：`at` 模式要 @机器人；`prefix` 模式要用前缀（默认 `#chat`） 4. 看控制台日志有没有报错 5. 用 `#ai调试开启` 打开调试模式看详细日志
API 报 401 / 403 / 429 - **401**：API Key 无效或过期 - **403**：Key 权限不足，或没有该模型的访问权限 - **429**：速率限制 —— 配多个渠道做负载均衡，或在渠道高级设置里配备选模型
Web 面板打不开 默认**共享 Yunzai 的端口**，访问路径是 `http://<你的地址>:/chatai`。 如果把配置里的 `web.sharePort` 关掉了，插件会用独立端口（默认 3000），这时要单独放行： ```bash netstat -tlnp | grep 3000 sudo ufw allow 3000 ```
内存占用高 1. 降低 `context.maxMessages`（最大历史消息数）和 `context.maxTokens` 2. 关掉不用的功能（记忆、MCP） 3. 用 `#结束对话` 清理上下文
怎么备份数据 数据都在 `plugins/hl-ai-plugin/data/` 和 `plugins/hl-ai-plugin/config/config.yaml`： ```bash # 备份 cp -r plugins/hl-ai-plugin/data ~/hlai-backup/ cp plugins/hl-ai-plugin/config/config.yaml ~/hlai-backup/ # 还原 cp -r ~/hlai-backup/data/* plugins/hl-ai-plugin/data/ cp ~/hlai-backup/config.yaml plugins/hl-ai-plugin/config/ ```
--- ## 📚 文档 | 文档 | 说明 | |------|------| | [docs/TOOLS.md](docs/TOOLS.md) | 工具与 MCP 开发完整指南 | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | MCP 与 Skills Agent 架构 | | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | 开发环境与规范 | | [docs/content/](docs/content/) | Wiki 详细文档（100+ 篇） | --- ## ⚠️ 免责声明 - 本插件仅供学习交流使用，请遵守相关法律法规与平台服务条款 - 使用 AI 服务需遵守对应服务商的条款 - 内置群管理工具（踢人、禁言等）属敏感操作，生产环境建议保持 `builtinTools.allowDangerous: false` - AI 生成内容可能有误，请勿完全依赖 - 开发者不对使用本插件造成的任何后果负责 --- ## 💖 鸣谢 - [chatai-plugin](https://github.com/XxxXTeam/chatai-plugin) —— 本插件的移植来源，功能与架构均来自该项目 - [chatgpt-plugin](https://github.com/ikechan8370/chatgpt-plugin) —— chatai-plugin 的原始项目 - [TRSS-Yunzai](https://github.com/TimeRainStarSky/Yunzai) · [Miao-Yunzai](https://github.com/yoimiya-kokomi/Miao-Yunzai) - [MCP Protocol](https://modelcontextprotocol.io/) ## 📄 许可证 [MIT](LICENSE)