Live2d Plugin for Halo

难道不想为您的网站添加一只萌萌的看板娘吗？？ (ノ≧∇≦)ノ |

简介

仅仅是一只可爱的看板娘哦！

注：本仓库仅提供基础渲染框架，不包含任何 Live2d 模型及其接口

Live2D Agent

当前版本的核心能力是让看板娘不只“会聊天”，还可以在站长授权范围内理解当前站点、调用工具并协助访客完成一些真实操作。

启用 AI 聊天后，站长可以在 插件设置 -> AI 聊天配置 中选择访问模式，分别控制匿名用户和登录用户是否只能对话，或同时允许使用 Agent 能力。Agent 能力不会因为旧版“公共聊天”配置自动开放，需要站长明确选择带 Agent 的访问模式。

内置 Agent 能力覆盖 Halo 站点的常见访问场景：

• 当前页面上下文：让模型知道访客当前在哪个页面、页面标题、路径、描述、选中文本，以及当前页面是否具备评论/留言入口。
• Halo 内容搜索：复用 Halo 自身全文搜索能力，帮助访客查找文章、独立页面等公开内容。
• Halo 资源导航：让模型打开后端查询得到的可信 Halo 资源，例如帮访客跳转到某篇文章、分类、标签或独立页面。
• 评论与留言辅助：可滚动到评论区、生成评论草稿；如站长开启提交能力，则在访客确认后尝试提交评论。
• 网络访问：允许模型通过后端读取站长白名单中的公网 URL，并内置阻止 localhost、内网、链路本地地址和未授权 Origin 的安全策略。

站长还可以通过“自定义 Agent 工具 JSON”扩展站点专属能力，例如打开主题里的联系面板、展示站长最新动态、触发自定义前台事件、滚动到指定区域或调用主题注册的浏览器工具。工具声明、参数、权限和是否需要确认都由站长配置，前台脚本只能绑定执行器，不能临时把未知工具暴露给模型。

Agent 的设计目标是：让看板娘能帮访客更快找到内容、理解当前页面并完成轻量站点操作，同时保持清晰的权限边界。

下载及使用说明

Tip

在 2.x 版本之后，插件依赖了 Ai Foundation 插件 ，因此安装此插件前请先安装 Ai Foundation 插件。

1. 前往 Halo 应用市场，安装 Ai Foundation 插件 插件。
2. 在 Github Release 下载 jar 包 或者前往 Halo 应用市场下载本插件。
3. 通过 Halo-2.x 安装插件 功能安装本插件
4. 打开网站，即可在左下角看到萌萌哒的看板娘哦~

开发说明

本仓库的现代化前端位于 packages/live2d，插件构建时会自动打包前端产物并同步到 Halo 插件静态资源目录。

前端单独开发时，可以直接在仓库根目录执行：

pnpm --dir packages/live2d dev

本地联调时，可以在 Halo 后台开启 插件设置 -> 高级设置 -> 前端调试模式，并让其指向本地 Vite 服务地址（默认 http://localhost:5173）。这样 Halo 页面会直接加载开发中的前端模块，方便调试现代化后的 Live2d 运行时。

功能介绍

• 一只萌萌的看板娘，为网站增添一份活力
• 支持 Cubism 2 / 3 / 4 / 5 模型
• 基于 OpenAi 的对话交互功能【会思考的萌娘】
• 一键换装、换肤
• 支持一言功能
• 小飞机游戏（把坏人全都打跑！）
• 自定义看板娘接口
• 支持外部自定义 TIPS 文件，更适合你的网站
• 支持自定义工具栏
• 支持 Agent 能力，让 AI 在授权范围内搜索 Halo 内容、打开可信资源并协助访客完成站点操作

自定义配置

此部分内容建议初步尝试过 Live2d 的用户观看。

自定义 Live2d 接口

若主题内置接口不满足用户使用，可以参考 live2d_api 自行开发接口。

之后修改 插件配置 -> 基本设置 -> Live2d 模型地址 即可。

自定义 TIPS 文件

默认 TIPS 文件 是一个 JSON 文件，其内容为 Live2d 消息框对用户各种事件的反馈。 例如当用户鼠标点击网页中的某个链接时，Live2d 的消息框就会呈现出各种各样的文本。而这个绑定事件就是通过 TIPS 文件来处理的。

因此可以说，TIPS 文件与所用主题强绑定甚至需要用户高度自定义。

默认的 TIPS 保证了用户的基础使用，但如果想丰富 Live2d，那么就需要自定义 TIPS 文件。本插件提供了多种方式自定义 TIPS。

TIPS 文件格式

{
  "mouseover": [                 // 鼠标移动事件
    "selector": "#live2d",       // css 选择器
    "text": []                   // Live2d 消息框显示内容。为数组则随机选择一条显示
  ],
  "click": [                     // 鼠标点击事件
    "selector": "#live2d",       // css 选择器
    "text": []                   // Live2d 消息框显示内容。为数组则随机选择一条显示
  ],
  "seasons": [                   // 日期事件，当前日期处于目标日期或目标区间内，则进行显示
    "date": "09/10",             // 日期或日期区间。区间使用 - 区分
    "text": []                   // Live2d 消息框显示内容。为数组则随机选择一条显示
  ],
  "time": [                      // 时间事件，到每日固定的时间则进行提示
    "hour": "6-7",               // 时间，小时为单位，需要为区间，例如 6-7 代表 6 点到 7 点之间
    "text": []                   // Live2d 消息框显示内容。为数组则随机选择一条显示
  ],
   "message": {                   // 固定消息，通常代表特定事件
     "default": [],               // 页面空闲时显示的消息
     "console": [],               // 打开控制台时显示的消息
     "copy": [],                  // 复制内容时显示的消息
     "loading": [],               // 模型加载时显示的消息
     "visibilitychange": []       // 多标签页，从其他标签页返回当前标签页时显示的消息
   }
 }

1. 使用主题提供的 TIPS 文件（推荐）

此功能属于为主题开发者定制。如果用户使用某款主题，但它并未支持此 TIPS 文件，不如向主题作者提交一个 ISSUE 吧！！！

由于 Live2d 的 TIPS 通常需要使用 css 选择器来进行鼠标定位，因此将 TIPS 文件交由主题来适配是最好的方式。

1. 主题开发者可以参考 主题 TIPS 文件 文件来编写适配自己主题的 TIPS 文件。
2. 将 json 文件命名为 tips.json 并放置在主题静态目录 assets/live2d/ 目录下

live2d 渲染页面时将自动读取当前启用主题下的文件。

注：主题所适配的 TIPS 只支持 mouseover 及 click 属性，主题提供的 TIPS 文件若与默认 TIPS 文件 css 选择器冲突，则以主题提供的为主

2. 使用插件配置单独制定 TIPS

当主题开发者未适配 Live2d 或者用户觉得其不太符合自己需求，那么可以使用插件内置的配置文件单独定制 TIPS 文件。

使用 Halo 后台 插件设置 -> 事件及提示语绑定 -> 选择器提示语 添加自己想要的提示语。

注：插件设置的 css 选择器与主题或默认的 TIPS 文件冲突时，将以插件设置的为准

3. 全量自定义 TIPS 文件

当用户想完全自定义 TIPS 文件或者上述两种方式不满足用户的需求，例如想更改 seasons, time, message 属性时，可以采用此种方式。

1. 用户可以参照 默认 TIPS 文件 或者按照 自定义TIPS文件 中的 TIPS 文件格式来编写 TIPS 文件。
2. 使用 Halo 后台 插件设置 -> 事件及提示语绑定 -> 自定义提示语文件，更改对应的文件即可。

小提示: 可以将文件上传到 Halo 附件内，再进行选择！

需要特别注意的是，一旦用户指定了此 TIPS 文件，运行时会优先将其作为完整 TIPS 文件加载；只有在文件缺失、格式不合法或加载失败时，才会回退到内置默认 TIPS，因此建议自定义时将属性设置完整

自定义工具

如果内置工具不满足需求，可以通过 Halo 后台 插件设置 -> 自定义工具 声明额外工具按钮。

当前自定义工具使用声明式动作。首批支持的动作包括：

• 发送提示语
• 显示、隐藏或切换看板娘
• 切换聊天窗口
• 切换模型或材质
• 截图
• 打开链接
• 触发命名空间自定义事件
• 加载指定模型

Agent 能力

启用 AI 聊天后，可以在 Halo 后台 插件设置 -> Agent 能力 配置模型可调用的站点能力。

AI 聊天访问模式分为四种：

• 匿名用户可对话：匿名和登录用户都能聊天，但不能使用 Agent 操作能力。
• 匿名用户可对话和使用 Agent：匿名和登录用户都能聊天，并可使用已启用的 Agent 能力。
• 登录用户可对话：只有登录用户能聊天，不能使用 Agent 操作能力。
• 登录用户可对话和使用 Agent：只有登录用户能聊天，并可使用已启用的 Agent 能力。

升级旧版本配置时，原“公共聊天”只会迁移到聊天模式，不会自动开放 Agent 能力。

内置预设能力包括：

• 当前页面上下文：读取页面标题、路径、描述和选中文本，不读取表单、Cookie 或本地存储。
• Halo 内容搜索：使用 Halo 自身全文搜索引擎查询公开内容。
• Halo 资源导航：仅能打开后端工具返回过的可信资源。
• 评论能力：关闭时不暴露评论工具；辅助模式可打开评论区、读取评论状态并生成评论草稿；提交模式需要站长明确启用，并在访客确认后尝试提交评论。
• 网络访问：通过后端读取站长白名单中的公网 URL，默认关闭；运行时会拒绝 localhost、内网、链路本地地址、未授权 Origin 和重定向访问。

站长可以通过“自定义 Agent 工具 JSON”声明浏览器侧工具。第一版支持的动作类型：

• navigate
• scroll-to
• highlight
• dispatch-event
• registered

这些工具可用于扩展主题或站点专属能力，例如：

• 打开自定义留言面板，并把模型生成的留言草稿交给主题处理。
• 展示站长最新动态、公告栏或个人资料区域。
• 跳转到主题内的特殊页面，或滚动并高亮某个内容区块。
• 调用主题脚本注册的受控浏览器能力。

示例：打开联系面板并把留言草稿交给主题处理：

[
  {
    "name": "open_contact_form",
    "enabled": true,
    "description": "打开站长留言面板，并传入留言草稿",
    "inputSchema": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "留言草稿"
        }
      },
      "required": ["message"]
    },
    "approval": "default",
    "requiredAuth": "none",
    "action": {
      "type": "dispatch-event",
      "event": "site:open-contact-form"
    }
  }
]

主题或前台脚本可以为已声明的 registered 工具绑定执行器：

window.Live2DAI?.registerTool("show_owner_updates", async ({ input }) => {
  window.dispatchEvent(new CustomEvent("site:show-updates", { detail: input }));
  return { ok: true };
});

运行时脚本只能绑定执行器，不能把新工具声明给模型。工具名称、描述、参数和权限必须来自插件设置。

安全边界：

• 不支持声明式 eval、任意 fetch、任意选择器点击或任意表单提交。
• 外部链接需要站长 allowlist，并默认请求访客确认。
• 工具执行结果会回传给模型，但不会直接把原始 JSON 展示给访客。

鸣谢

• 本插件代码借鉴了 live2d-widget 的理念并完全重写
• 使用了 hitokoto 的一言接口
• 默认使用了 ZSQIM 的 live2d 接口
• 使用了 untitled-pixi-live2d-engine 的 Live2d 渲染引擎，用于支持 Cubism 2 / 3 / 4 / 5 模型
• 纸飞机小游戏源自于 WebsiteAsteroids
• Live2d 官方地址 https://live2d.github.io

许可证

plugin-live2d © LIlGG，基于 MIT 许可证发行。

本仓库所使用的接口等版权均属原作者，仅供研究学习，不得用于商业用途，请善待接口。

作者及其贡献者共有版权 （帮助维护列表 ）

lixingyong.com · GitHub @LIlGG

希望你喜欢！