内容
# Spine Companion
[English](README.md) | [简体中文](README.zh-CN.md)
开源桌面端伴侣，用于 Spine 3.8 模型。目前的运行时聚焦于 Tauri，同时保留了 Electron 路径以确保兼容性。渲染器使用 `pixi.js@6.5.10` 和 `pixi-spine@3.1.2` 直接渲染 `.skel/.atlas/.png` 文件，支持透明背景、始终置顶窗口行为、拖拽、缩放、点击交互、状态转换、本地状态 API、MCP 桥接、进度气泡、托盘控件、简单提醒和类似工具的管理窗口。
## 资产政策
本仓库不包含《命运之冠》、Ark-Models 或其他受版权保护的模型资产。如有合法权利，请仅将它们用作本地测试材料。仓库中仅保留代码、示例和设置说明。
本地资产配置写入 `companion.local.json`，该文件被 git 忽略。
## 快速开始
### 使用发布版本
1. 从 GitHub Release 下载最新的 Windows 安装程序或便携式版本。
2. 建议将 `companion.local.json` 放在用户配置文件夹中：
```text
%APPDATA%\spine-companion\companion.local.json
```
您也可以将其放在 exe 文件旁边：
```json
{
"spine": {
"assetDir": "C:\\path\\to\\spine_model_folder",
"skel": "model.skel"
}
}
```
3. 双击应用程序。使用托盘菜单打开配置文件夹、显示状态面板、打开管理窗口、缩放、切换状态和退出。
### 从源码运行
```bash
bun install
bun run setup:assets -- "C:\path\to\amiya_spine"
bun run dev
```
从源码运行 Tauri 候选版本：
```bash
bun run tauri:dev
```
有关详细的部署、启动、MCP 和故障排除步骤，请参阅 [docs/deployment.md](docs/deployment.md)。有关 UI 重点介绍，请参阅 [docs/user-guide.md](docs/user-guide.md)。
计划中的 AI 辅助角色工作流程记录在 [docs/avatar-studio.md](docs/avatar-studio.md) 中。
渲染器预览版可在：
```text
http://127.0.0.1:17389?api=http://127.0.0.1:17388
```
仅用于浏览器预览，无需启动 Electron：
```bash
bun run dev:renderer
bun run dev:api
```
MVP 意味着这是最小的可用的垂直切片：桌面外壳、实时 Spine 渲染、状态切换、本地状态 API、提醒和 MCP 桥接。它不是一个精灵导出路径。
## 本地状态 API
默认 API 监听 `http://127.0.0.1:17388`。
```bash
curl http://127.0.0.1:17388/state
curl -X POST http://127.0.0.1:17388/state -H "Content-Type: application/json" -d "{\"state\":\"working\",\"source\":\"curl\"}"
curl -X POST http://127.0.0.1:17388/reminders -H "Content-Type: application/json" -d "{\"text\":\"stand up\",\"inSeconds\":30}"
```
状态事件也可通过以下方式获得：
- SSE：`GET /events`
- WebSocket：`ws://127.0.0.1:17388/ws`
## Codex MCP 桥接
MCP 服务器允许 Codex 通过本地 API 读取和更新伴侣。
```bash
bun run mcp:install:codex
```
这将一个 `spine_companion` MCP 服务器条目追加到 `~/.codex/config.toml`。在安装后，请重启 Codex 或打开一个新的会话。
可用的 MCP 工具：
- `companion_get_state`
- `companion_set_state`
- `companion_reminder`
- `companion_report_codex_phase`
伴侣应用程序或 API 必须在 Codex 使用 MCP 桥接时运行。
要安装可重用的状态报告技能并配置常见的 AI 工具：
```bash
bun run skill:install
bun run ai:configure -- --target all
```
支持的目标包括 Codex Desktop、Codex CLI、Cursor、Claude Desktop、Claude Code 和 Claude CLI。 不支持的 MCP 工具可以复制 [docs/ai-tools.md](docs/ai-tools.md) 中的 JSON 代码片段。
## 一键式 Codex 插件
仓库中包含一个本地 Codex 插件：
```text
plugins/spine-companion-status
```
支持存储库市场文件 Codex 环境可以从 `.agents/plugins/marketplace.json` 安装 `Spine Companion Status`。该插件提供状态报告技能和 `spine_companion` MCP 桥接配置，默认情况下使用 Bun 启动。
## 状态和动画
| 状态 | Spine 动画 |
| --- | --- |
| `idle` | `Relax` |
| `working` | `Relax` |
| `running` | `Move` |
| `reminder` | `Interact` |
| `waiting` | `Sit` |
| `failed` | `Sleep` |
| `sleeping` | `Sleep` |
| `reviewing` | `Special`，可配置 `review` 分段 |
| `success` | `Special`，可配置 `success` 分段 |
动画更改使用 Spine 运行时混合，通过 `stateData.setMix` 和每个转换的 `mixDuration`。渲染器在启动时采样所有映射的状态动画，并使用一个稳定的显示帧，因此 `Sit`、`Sleep`、`Move` 和 `Special` 保持在一个一致的大小范围内。`Special` 分段在 `companion.config.json` 中配置。
## 提供者层
渲染器支持以下状态源：
- Electron IPC，用于桌面应用程序。
- 本地 HTTP 轮询，用于浏览器预览和简单集成。
- JSON 轮询，用于编写状态文件的脚本。
- WebSocket，用于推送样式的桥接服务。
有关 MCP 桥接的预期形状，请参阅 [docs/architecture.md](docs/architecture.md)。
## 桌面控件
Windows 托盘菜单可以显示或隐藏状态面板、切换始终置顶、显示或隐藏进度气泡、缩放模型、重置大小、切换状态和退出。拖动透明舞台移动窗口；水平拖动暂时切换到 `running` 并镜像模型左右。
管理器包括可搜索的模型库、已安装的模型操作、下载状态、热应用的缩放和偏移设置、诊断、更新检查和最近的状态历史。捆绑的 Ark-Models 目录条目仅下载到本地配置文件夹；此仓库和公共版本不包含模型资产文件。
## 常见问题
**为什么应用程序显示缺少资产？**
打开管理器 > 诊断并确认活动模型文件夹包含 `.skel`、`.atlas` 和 `.png` 文件。如果模型通过库下载，请尝试从已安装中设置活动模型。
**为什么 Codex 一直处于空闲状态？**
MCP 桥接仅在伴侣应用程序或本地 API 运行时工作。运行 `bun run mcp:install:codex`，重启 Codex 并检查管理器 > 诊断。
**我应该使用哪个运行时？**
使用 Tauri 版本进行当前测试。 Electron 路径保留在仓库中以确保兼容性，但新的用户界面功能针对 Tauri。
## 开源说明
- 不要提交受版权保护的模型的 `.skel`、`.atlas` 或纹理文件。
- 在 `companion.local.json` 或环境变量中保留本地模型路径。
- 使用 `companion.config.example.json` 作为公共模板。
- `assets/` 下的占位目录仅用于记录放置位置。
## macOS 发布签名
GitHub Actions 可以构建未签名的 macOS 工件，但 Apple Silicon 用户可能会看到 Gatekeeper 错误，例如“损坏”或“无法打开”。对于公共 macOS 下载，请配置这些仓库机密，以便 electron-builder 可以签名和 notarize DMG/ZIP 资产：
- `MACOS_CERTIFICATE`
- `MACOS_CERTIFICATE_PASSWORD`
- `APPLE_API_KEY`
- `APPLE_API_KEY_ID`
- `APPLE_API_ISSUER`
- `APPLE_TEAM_ID`
