<p align="center">
  <img src="./public/assets/avatar.png" alt="Persona" width="132" />
</p>

<h1 align="center">Persona</h1>

<p align="center">
  <strong>让 AI 不只会回答，也能以角色的方式陪伴在桌面上。</strong>
</p>

<p align="center">
  一个支持 VRM、VRMA、语音状态联动与 MCP 控制的跨平台桌面虚拟角色。
</p>

<p align="center">
  <a href="https://github.com/staro1314/codex-persona/actions/workflows/ci.yml"><img src="https://github.com/staro1314/codex-persona/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-4f7cff" alt="Windows, macOS and Linux" />
  <img src="https://img.shields.io/badge/VRM%20%2F%20VRMA-supported-ff78b7" alt="VRM and VRMA supported" />
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-35b779" alt="MIT License" /></a>
</p>

<p align="center">
  <img src="./docs/images/persona-client-showcase.webp" alt="Persona 中文客户端、模型库、实时预览与桌面悬浮角色" width="100%" />
</p>

<p align="center">
  <sub>真实客户端效果：中文模型库、实时角色预览与透明置顶悬浮角色。画面中的模型由用户在本机导入，不随本仓库分发。</sub>
</p>

## Persona 是什么？

Persona 是一个开源的桌面虚拟角色应用。它把本地 VRM 角色放到桌面最前端，并根据语音输出、待机策略或 AI 工具调用切换 VRMA 动作，让 Codex 等 AI 助手从“聊天窗口”变成有表情、有动作、有存在感的桌面伙伴。

它既可以独立运行，也可以通过本地 MCP 服务被 AI 控制。模型、动作和配置默认保存在本机；Persona 不录制麦克风、不保存音频、不转写内容，也不会把音频发送到网络。

## 成品能力

- **桌面悬浮角色**：透明、置顶、可拖动、可缩放，并可调整悬浮区域，减少对下层页面点击的遮挡。
- **VRM 模型库**：导入多个 `.vrm` 模型，自定义名称、预览效果并切换默认角色。
- **VRMA 动作库**：支持待机、说话、思考、问候、开心、手枪手势、舞蹈及自定义动作卡片。
- **多动作编排**：保留 VRMA 原文件名，支持拖动排序，并可选择固定片段、随机单次或持续轮询。
- **语音状态联动**：监听受支持应用的播放进程，在说话开始与结束时自动切换角色动作。
- **AI / MCP 控制**：Codex 等 MCP 客户端可以播放动作、显示或隐藏角色，并读取运行状态。
- **中英文界面**：客户端支持简体中文与英文切换。

<p align="center">
  <img src="./docs/images/persona-settings-zh.webp" alt="Persona 中文设置界面、模型库与角色预览" width="100%" />
</p>

<p align="center">
  <sub>中文设置界面：管理模型、预览角色、修改名称，并配置动作资源库。</sub>
</p>

## 它如何工作？

1. 在设置中导入一个本地 `.vrm` 模型。
2. 为待机、说话、思考等状态添加 `.vrma` 动作，并选择播放策略。
3. Persona 根据语音状态自动切换动作，或接受 MCP 客户端的显式控制。

角色窗口本身保持简洁：滚轮缩放，左键拖动旋转视角，右键拖动平移模型；窗口位置可通过拖动悬浮把手调整。

## 快速开始

环境要求：Node.js 24 或更高版本、npm，以及支持硬件加速的桌面环境。

```bash
git clone https://github.com/staro1314/codex-persona.git
cd codex-persona
npm install
```

Windows 和 macOS 首次从源码运行前，需要构建本地语音监听器：

```bash
npm run native:build
npm run native:test
```

启动 Persona：

```bash
npm run demo
```

源码目录提供了跨平台的一键启动入口。它们会在缺少依赖或构建产物时自动补齐，
日常启动则直接打开 Persona；重复启动会唤出已经运行的角色窗口：

- Windows：双击 [`start-persona.cmd`](./start-persona.cmd)
- macOS：双击 [`start-persona.command`](./start-persona.command)
- 两个平台的终端通用命令：`npm run launch`

macOS 首次使用源码启动脚本时，如果系统未保留可执行权限，请先运行
`chmod +x start-persona.command`。正式发布的 DMG 不需要执行这一步。

首次启动会自动打开设置页。导入 `.vrm` 后，首个模型会成为默认模型；随后可以在动作库中添加 `.vrma` 文件。后台启动可使用：

```bash
npm start -- --background
```

> 仓库不会分发演示截图中的角色模型，也不会默认携带来源与授权不明确的 VRM / VRMA 资源。

## 连接 Codex

保持 Persona 运行，然后注册本地 MCP 服务：

```bash
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/`，并在以下文件中登记：

```text
public/assets/
├── library.json
├── library.json.example
├── manifest.json
├── manifest.json.example
├── models/
└── animations/
```

`manifest.json` 中必须填写来源、许可和分发状态。发布检查会拒绝来源不完整或未明确允许分发的资源。详见 [资源许可说明](./ASSET_LICENSES.md)。

## 平台支持

| 平台 | 自动语音输出监听 | 构建产物 |
| --- | --- | --- |
| 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 不捕获麦克风，不生成语音，也不保存、转写或上传音频。

## 构建与开发

在目标操作系统上构建对应安装包：

```bash
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。

提交前可运行完整检查：

```bash
npm run check
npm run native:build
npm run native:test
```

更多资料：

- [架构与开发说明](./docs/DEVELOPMENT.md)
- [Codex 与集成 API](./docs/INTEGRATIONS.md)
- [发布流程](./docs/RELEASING.md)
- [安全策略](./SECURITY.md)

## 项目关系

本项目基于 [xikhar/persona](https://github.com/xikhar/persona) 持续扩展。本分支重点补充了中文国际化、模型与动作资源库、动作播放策略、可调桌面悬浮窗口、Windows 语音状态联动和 MCP 使用体验。

欢迎提交 Issue、改进动作类型、补充翻译，或分享你制作并拥有分发权的 VRM / VRMA 资源。

## License

Persona 应用源码采用 [MIT License](./LICENSE)。角色模型、动作和其他第三方素材不自动包含在该许可中，发布前请分别确认其使用与分发授权。