AI导哈

Live2D桌面伴侣

一个基于Electron的桌面Live2D陪伴应用，通过监听AI进程的系统输出电平驱动角色口型，并控制表情和动作，适用于AI助手视觉陪伴场景。

  • by Mitscherlich
  • JavaScript
  • 本地部署
  • 12 星标
  • 更新于
在 GitHub 查看 Mitscherlich/live2d-mcp

使用说明

Live2D Desktop Companion

Electron 桌面 Live2D 陪伴应用：监听 Codex / ChatGPT 等 agent 进程的系统输出电平驱动口型，并通过本机 MCP 控制表情、动作和角色窗口。

应用只做视觉陪伴：不提供 TTS、不播放 agent 音频、不采集麦克风、不落盘或上传音频，也不使用 VRM/Three 渲染管线。

  • 产品规格：SPEC.md
  • 架构说明：docs/ARCHITECTURE.md
  • 默认 bridge：127.0.0.1:47832（仅 loopback）
  • 默认 MCP URL：http://127.0.0.1:47832/mcp

快速开始（Electron 默认路径）

需要 Bun 1.1+（以及 Node.js 20+ 以运行 Electron / node:test）；macOS 是当前原生 voice listener 的优先平台。

1. 安装依赖

bun install

2. 准备 Cubism Core 与模型

  1. 取得 Cubism Core 4.x 的 live2dcubismcore.min.js，放入 renderer/public/。
    • 本项目使用 pixi-live2d-display 的 Cubism4 运行时，请勿使用 Cubism 5 SDK 的 Core 6.x（会加载成功但画面空白，并可能在渲染时报错）。
    • 推荐：Cubism SDK for Web 4-r.x 的 Core/live2dcubismcore.min.js，或与 pixi-live2d-display 示例配套的 4.2 Core。
  2. 从 Live2D 示例模型 下载 HiyoriPro，将 runtime 内容放入 renderer/public/model/HiyoriPro/（需含 hiyori_pro_t11.model3.json 与贴图/motion）。

目录应为：

renderer/public/
├── live2dcubismcore.min.js
└── model/
    └── HiyoriPro/
        ├── hiyori_pro_t11.model3.json
        └── ...

缺少这些资源不会让应用硬崩；角色窗会显示准备指引。生产构建在补齐资源后需要重新执行 bun run build。

3. 启动桌面应用

开发模式（Vite + Electron）：

bun run dev

生产构建与启动：

bun run build
bun start

启动后系统托盘提供“显示角色窗”“隐藏角色窗”“重置窗口位置”“打开设置”“退出”。关闭角色窗只会隐藏它，应用和 MCP bridge 由托盘保活；请从托盘“退出”结束应用。

角色窗的位置、大小和 CSS 缩放比例会实时保存到 Electron userData/settings.json，下次启动自动恢复；恢复位置会沿用至少保留 80×40px 可见区域的边界 snap 规则。锁定状态不保存，每次启动默认可交互。托盘“重置窗口位置”会恢复右下角的 600×640、100% 默认状态。

4. 连接 Codex MCP

应用运行时执行：

codex mcp add live2d --url http://127.0.0.1:47832/mcp

同一 URL 也可用于 Claude Code、Hermes 等支持 Streamable HTTP MCP 的客户端。托盘“打开设置”会展示与 bridge 实际监听端口一致的 MCP URL 和可复制的 Codex 命令。

若设置了自定义端口：

LIVE2D_BRIDGE_PORT=49000 bun run dev
codex mcp add live2d --url http://127.0.0.1:49000/mcp

bridge 永远只绑定 loopback。可用以下接口排障或注入 external voice 事件：

curl -s http://127.0.0.1:47832/health

curl -s -X POST http://127.0.0.1:47832/events \
  -H 'content-type: application/json' \
  -d '{"type":"state","state":{"phase":"active","activity":"speaking"}}'

curl -s -X POST http://127.0.0.1:47832/events \
  -H 'content-type: application/json' \
  -d '{"type":"audio-level","level":0.8}'

Voice source 设置

托盘 →“打开设置”可选择四种模式。设置写入 Electron userData/settings.json；合法变更会立即重启 listener，无需重启应用。非法 mode、正则或 application source 不会覆盖上一份有效配置。

模式 行为 必要字段
automatic 默认按 Codex / ChatGPT / OpenAI 类进程名匹配 无
application 精确监听一个 application source source_id 与 source_name
custom 用自定义正则匹配目标进程 process_pattern（合法正则，最多 200 字符）
external 完全关闭原生进程捕获，只消费 loopback POST /events 无

现有环境变量仍可覆盖持久化设置：

变量 说明
LIVE2D_VOICE_SOURCE_MODE automatic / application / custom / external
LIVE2D_TARGET_PROCESS_PATTERN automatic 的匹配覆盖，或 custom 正则
LIVE2D_VOICE_SOURCE_ID application source ID
LIVE2D_VOICE_SOURCE_NAME application 展示名
LIVE2D_NATIVE_HELPER_PATH macOS native helper 路径覆盖（排障用）
LIVE2D_LISTENER_DEBUG=1 输出 listener 协议诊断，不输出音频内容
LIVE2D_UI_CHROME=1 Electron 角色窗显示顶部状态栏 + 底部调试条（默认隐藏）
LIVE2D_DEVTOOLS=1 打开 DevTools，并同时显示角色窗工具条
LIVE2D_RENDERER_LOG=1 把 renderer console 汇入终端（不打开工具条）

角色窗 UI 工具条

  • 默认：隐藏顶栏/底栏，只保留角色与透明背景（顶部仍有隐形拖拽区可移动窗口）。
  • 调试时打开工具条（任选其一）：
    • LIVE2D_UI_CHROME=1 bun run dev
    • 或 URL 加 ?debug=1 / ?ui=1
    • 或 DevTools：LIVE2D_DEVTOOLS=1 bun run dev
    • 或在 renderer 控制台：localStorage.setItem('live2d.uiChrome','1'); location.reload()

设置窗检测到环境变量覆盖时会明确提示：表单仍会持久化，但当前进程继续采用环境变量；移除覆盖并重启后才使用已保存值。

macOS 权限与 external 降级

automatic / application / custom 使用 macOS 进程系统音频监听，需要在“系统设置 → 隐私与安全性 → 屏幕与系统音频录制”中授权运行 Electron/终端的宿主应用。权限不足时 /health 与 MCP get_status 会报告 permission-denied；helper 缺失或不可用则报告 unavailable。

权限暂不可用时切换到 external，应用不会启动 native helper，仍可通过 /events 驱动口型。该降级路径同样不采麦克风、不含 TTS。

如需从源码构建 macOS universal helper：

bun run build:native

MCP 工具

工具 说明
get_status 查询窗口、bridge、voice/listener 与模型状态
control_window show / hide / toggle 角色窗
get_model_info 获取表情、动作组与参数摘要
set_expression 切换表情
play_motion 播放动作
look_at 控制视线方向
set_parameter 设置 Live2D 参数
reset 重置表情、动作、视线与参数

不存在 speak、lip_sync* 或其他 TTS 工具。

验证

bun run build
bun run test
bun run proof:f4
bun run proof:f5
bun run proof:f6

请使用 bun run test 执行本仓库 package.json 中的 node:test 套件。裸命令 bun test 会进入 Bun 内置测试器，与本仓库脚本无关。

相关 MCP