让 AI 不只会回答，也能以角色的方式陪伴在桌面上。
一个支持 VRM、VRMA、语音状态联动与 MCP 控制的跨平台桌面虚拟角色。
真实客户端效果：中文模型库、实时角色预览与透明置顶悬浮角色。画面中的模型由用户在本机导入，不随本仓库分发。
Persona 是一个开源的桌面虚拟角色应用。它把本地 VRM 角色放到桌面最前端，并根据语音输出、待机策略或 AI 工具调用切换 VRMA 动作，让 Codex 等 AI 助手从“聊天窗口”变成有表情、有动作、有存在感的桌面伙伴。
它既可以独立运行，也可以通过本地 MCP 服务被 AI 控制。模型、动作和配置默认保存在本机；Persona 不录制麦克风、不保存音频、不转写内容，也不会把音频发送到网络。
- 桌面悬浮角色：透明、置顶、可拖动、可缩放，并可调整悬浮区域，减少对下层页面点击的遮挡。
- VRM 模型库：导入多个
.vrm模型，自定义名称、预览效果并切换默认角色。 - VRMA 动作库：支持待机、说话、思考、问候、开心、手枪手势、舞蹈及自定义动作卡片。
- 多动作编排：保留 VRMA 原文件名，支持拖动排序，并可选择固定片段、随机单次或持续轮询。
- 语音状态联动：监听受支持应用的播放进程，在说话开始与结束时自动切换角色动作。
- AI / MCP 控制：Codex 等 MCP 客户端可以播放动作、显示或隐藏角色，并读取运行状态。
- 中英文界面：客户端支持简体中文与英文切换。
中文设置界面：管理模型、预览角色、修改名称，并配置动作资源库。
- 在设置中导入一个本地
.vrm模型。 - 为待机、说话、思考等状态添加
.vrma动作，并选择播放策略。 - Persona 根据语音状态自动切换动作，或接受 MCP 客户端的显式控制。
角色窗口本身保持简洁：滚轮缩放，左键拖动旋转视角，右键拖动平移模型；窗口位置可通过拖动悬浮把手调整。
环境要求：Node.js 24 或更高版本、npm，以及支持硬件加速的桌面环境。
git clone https://github.com/staro1314/codex-persona.git
cd codex-persona
npm installWindows 和 macOS 首次从源码运行前，需要构建本地语音监听器：
npm run native:build
npm run native:test启动 Persona：
npm run demo源码目录提供了跨平台的一键启动入口。它们会在缺少依赖或构建产物时自动补齐， 日常启动则直接打开 Persona；重复启动会唤出已经运行的角色窗口：
- Windows：双击
start-persona.cmd - macOS：双击
start-persona.command - 两个平台的终端通用命令：
npm run launch
macOS 首次使用源码启动脚本时，如果系统未保留可执行权限，请先运行
chmod +x start-persona.command。正式发布的 DMG 不需要执行这一步。
首次启动会自动打开设置页。导入 .vrm 后，首个模型会成为默认模型；随后可以在动作库中添加 .vrma 文件。后台启动可使用：
npm start -- --background仓库不会分发演示截图中的角色模型，也不会默认携带来源与授权不明确的 VRM / VRMA 资源。
保持 Persona 运行，然后注册本地 MCP 服务：
codex mcp add persona --url http://127.0.0.1:47831/mcp新建 Codex 会话后，可以直接尝试：
- “让 Persona 做一个开心动作。”
- “让角色进入思考状态。”
- “隐藏 Persona，完成后再显示。”
- “检查 Persona 和语音监听器是否正常运行。”
MCP 只开放 Persona 自身的显示、动作与状态能力，不会让客户端访问其他桌面内容。
Persona 内置永久的待机与说话动作槽，也支持思考、问候、开心、手枪手势、舞蹈和自定义类型。每张动作卡片可以包含多个 VRMA 片段：
- 固定片段：正式运行时始终播放指定动作。
- 随机单次：每次进入该状态时随机选择一个动作。
- 持续轮询：停留在该状态期间，按当前顺序持续切换动作。
导入的资源与用户配置保存在 Persona 的本地应用数据中。打包资源保持只读；修改打包动作时会创建用户级覆盖，重置后可恢复原始配置。
如需制作可公开分发的资源包，请把模型放在 public/assets/models/，动作放在 public/assets/animations/，并在以下文件中登记：
public/assets/
├── library.json
├── library.json.example
├── manifest.json
├── manifest.json.example
├── models/
└── animations/
manifest.json 中必须填写来源、许可和分发状态。发布检查会拒绝来源不完整或未明确允许分发的资源。详见 资源许可说明。
| 平台 | 自动语音输出监听 | 构建产物 |
|---|---|---|
| Windows | WASAPI 进程级回环捕获 | NSIS 安装包 |
| macOS 14.2+ | Core Audio Process Tap | DMG、ZIP（arm64 / x64） |
| Linux | PipeWire 进程流捕获 | AppImage、DEB |
Linux 需要在 PATH 中提供 pw-dump 和 pw-record；Windows 进程回环监听需要 Windows 10 build 20348 或更高版本；macOS 首次运行会请求“系统音频录制”权限。
每种监听器都只关注受支持应用的播放进程。Persona 不捕获麦克风，不生成语音，也不保存、转写或上传音频。
在目标操作系统上构建对应安装包：
npm run dist:windows
npm run dist:mac
npm run dist:linux产物写入 release/。Windows 需要安装带 C++ 桌面开发工作负载的 Visual Studio Build Tools；macOS 需要 Xcode Command Line Tools 和 macOS 14.2+ SDK。
提交前可运行完整检查：
npm run check
npm run native:build
npm run native:test更多资料：
本项目基于 xikhar/persona 持续扩展。本分支重点补充了中文国际化、模型与动作资源库、动作播放策略、可调桌面悬浮窗口、Windows 语音状态联动和 MCP 使用体验。
欢迎提交 Issue、改进动作类型、补充翻译，或分享你制作并拥有分发权的 VRM / VRMA 资源。
Persona 应用源码采用 MIT License。角色模型、动作和其他第三方素材不自动包含在该许可中，发布前请分别确认其使用与分发授权。