AI RolePlay for Halo

AI RolePlay 是面向 Halo 2.25.4+ 的 AI 角色扮演插件。所有模型发现、Provider 密钥和模型调用都由
Halo AI Foundation 提供，本插件不实现任何厂商大模型客户端。

功能

• 从 AI Foundation 自动读取语言模型，支持插件默认模型和角色专属模型。
• UC 新增“AI”内容分组及其下的“角色扮演”，包含角色大厅、逐字回复、历史会话和首次协议确认。
• 角色支持从 Halo 附件库选择头像和 16:9 封面图。
• Console 包含仪表盘、模型、角色、聊天记录、用户、协议、会话处置与权限管理。
• 聊天不产生逐条审核任务；管理员按需查看完整会话，并可封禁或解封不合适的会话。
• 支持单角色/全部 AI 封禁、永久/限时封禁、聊天搜索、删除和 CSV 导出。
• “使用 AI 角色扮演”是可单独分配给普通用户的 Halo RoleTemplate。
• 6 个 Halo Custom Extension 数据模型，兼容 Halo 支持的底层数据库。

兼容版本

• Halo 2.25.4+
• Java 21
• AI Foundation 1.0.0（插件依赖范围 <2.0.0）
• Node.js 24、pnpm 10

构建

./gradlew clean build

Windows：

.\gradlew.bat clean build

产物位于 build/libs/plugin-ai-roleplay-1.3.1.jar。

本地开发

1. 先在 Halo 中安装并启用 AI Foundation，至少配置一个可用语言模型。
2. 启动开发服务器：

./gradlew haloServer

3. 打开 http://localhost:8090/console，默认账号密码均为 admin。
4. 在 Halo 用户/角色管理中为普通用户分配“使用 AI 角色扮演”权限。
5. 在插件设置中选择默认语言模型；随后在 UC 的“AI”分组下进入“角色扮演”。

数据模型与 Migration

Halo 最新插件规范使用 Extension Store，而不是插件直接维护数据库方言相关的物理表。逻辑映射如下：

会话处置字段保存在 AiChatSession 中，AiChatMessage 不维护逐条审核状态。

V001SeedDataMigration 在首次启动时幂等创建默认服务协议和四个示例角色，不覆盖管理员数据。

AI Foundation 调用

后端通过 Halo 跨插件扩展点获取模型服务：

extensionGetter.getEnabledExtension(AiModelService.class)
    .flatMap(service -> service.languageModel(modelName))
    .flatMap(model -> model.generateText(request));

modelName 始终为 AiModel.metadata.name。API Key、Base URL、Provider 适配和模型发现均留在 AI Foundation 中。

权限与会话处置

• 普通用户必须被明确授予“使用 AI 角色扮演”RoleTemplate 才能看到 UC 入口并调用 UC API。
• 管理员可以从聊天记录进入完整对话；封禁后会话仍可查看，但用户不能继续发送，管理员可随时解封。
• 会话 API 校验当前登录用户所有权；Console API 由 Halo RBAC 保护。
• 系统提示词加入防泄露、危机处理和禁止依赖规则。
• 聊天内容会持久化，首次协议明确说明管理员查看、导出和删除范围。

作者与支持