内容
# Mint Three.js 配置
> 将您的编码代理转换为**远程 3D 引擎** — 通过 [Mint MCP](https://mcp.mint.gg/mcp) 生成模型、世界、PBR 材料、资产包和音频，然后使用 [`mint-threejs-skills`](https://github.com/mintdotgg/mint-threejs-skills) 在其周围构建浏览器 **Three.js** 应用程序/游戏。无需本地 GPU，无需模型下载 — 基于积分，免费试用可用。
---
## 本仓库包含的内容
| 路径 | 内容 |
|------|----------|
| `skills/mint-mcp-3d-engine/` | Hermes 技能：连接 Mint MCP + OAuth 承载流，无头主机配方，工作脚本 |
| `skills/mint-threejs-skills/` | Mint 官方 Three.js 技能套件（应用程序/游戏导演，视觉/交互系统，质量保证，调试） |
| `scripts/mint_generate.py` | 通过 Mint MCP 生成模型并下载 GLB |
| `scripts/mint_refresh_token.py` | OAuth令牌自动刷新（在过期前运行于 cron） |
| `assets/install-demo.gif` | 安装动画演示 |
| `LICENSE` | MIT |
---
## 步骤 1 — 先决条件
- **Node.js** ≥ 18（用于 `npx skills`）
- **Hermes Agent** 支持 MCP（或任何读取 `~/.hermes/skills` 的代理）
- 一个 **Mint** 账户 — 免费，在 [mint.gg](https://mint.gg) 注册（Google/邮箱）
- Git
```bash
node --version # 需要 v18+
hermes --version # 任何最近的带有 mcp_servers 支持的构建
```
---
## 步骤 2 — 克隆此仓库
```bash
git clone https://github.com/Celebez/mint-threejs-setup.git
cd mint-threejs-setup
```
`skills/` 下的技能文件夹已准备好符号链接/复制到您的代理中。
---
## 步骤 3 — 安装 Three.js 技能
```bash
npx skills add mintdotgg/mint-threejs-skills -g -y
```
这会克隆官方套件并 **自动符号链接到 Hermes Agent**（`~/.hermes/skills/mint-threejs-skills`）。该套件包括：
- `threejs-app-director` — 产品配置器，查看器，交互式体验
- `threejs-game-director` — 具有完整可玩循环的游戏
- `threejs-visual-systems` — 照明，反射，材料
- `threejs-interaction-systems` — 轨道相机，选择器，控件
- `threejs-gameplay-systems` / `threejs-game-ui-designer` — 游戏逻辑 + UI
- `threejs-debug-profiler` / `threejs-qa-release` — 调试和验证
> 另外，将捆绑的 `mint-mcp-3d-engine` 技能复制到您的代理的技能目录中：
> ```bash
> cp -r skills/mint-mcp-3d-engine ~/.hermes/skills/
> ```
---
## 步骤 4 — 将 Mint MCP 连接到 Hermes
在 `~/.hermes/config.yaml` 中将服务器添加到 `mcp_servers:` 下：
```yaml
mcp_servers:
mint-mcp:
url: https://mcp.mint.gg/mcp
auth: oauth
enabled: true
```
然后进行身份验证。**在桌面（交互式）主机上：**
```bash
hermes mcp login mint-mcp
```
浏览器打开 → 登录到 Mint → 批准范围（`mint:read`，`mint:generate:start`，`mint:generate:approve`）。完成。
### 无头主机（盒子上没有浏览器）
`hermes mcp login` 在非交互式主机上失败。您自己运行 OAuth 交换：DCR + PKCE +令牌交换，然后将令牌放到 `$HERMES_HOME/mcp-tokens/mint-mcp.json`（模式 `0600`）。完整的逐步说明，包括可重用的循环监听器，在 [`skills/mint-mcp-3d-engine/references/headless-oauth-recipe.md`](skills/mint-mcp-3d-engine/references/headless-oauth-recipe.md) 中。
> ⚠️ **关键注意事项：** 批准的浏览器 **必须** 在与监听器 **相同的** 主机上运行，而不是不同的机器。`redirect_uri` 是循环地址；另一个机器上的浏览器重定向到其自己的 localhost，代码是一次性的 — 它被烧毁了。
验证：
```bash
hermes mcp test mint-mcp
# ✓ 已连接 ✓ 已发现工具：37
```
---
## 步骤 5 — 保持令牌新鲜（cron，无 LLM）
Mint 令牌在 **1 小时** 后过期。捆绑的 `scripts/mint_refresh_token.py` 通过 `refresh_token` 刷新并重写令牌文件（仅当剩余 < 10 分钟时）。每 50 分钟安排一次：
```bash
# Hermes cron（no_agent = 无 LLM 成本）
hermes cron create --name mint-refresh --schedule "*/50 * * * *" \
--no-agent --script mint_refresh_token.py
```
或普通的 systemd 定时器 / crontab 行：`*/50 * * * * python3 /path/mint_refresh_token.py`。
---
## 步骤 6 — 生成您的第一个 3D 资产
```bash
python3 scripts/mint_generate.py "一个现代简约的交易工作站桌面，双显示器与外汇图表，翡翠仪表盘，黑暗高级"
```
这开始生成，轮询直到 `succeeded`/`final`，然后下载 GLB（+ 预览 webp）到 `~/mint_3d/`。一次生成 ≈ **11 积分** 在 Explorer 试用版（20,000 免费积分/月）。
或者直接询问您的代理：
> “使用 Mint MCP 从文本提示创建交易工作站。自动运行生成，等待完成的神器，返回可下载的 GLB。”
---
## 步骤 7 — 构建 Three.js 应用程序
加载 `mint-threejs-skills` 并描述您想要的。对于您刚刚拉取的 GLB 的查看器/配置器：
> “为 `trading-workstation.glb` 构建一个响应式 Three.js 产品查看器。轨道控件，一个明亮的检查湾，材料选择，相机预设。使用 Mint MCP 仅作为资产管道 — 永远不要在浏览器代码中调用 MCP。”
技能在构建前呈现 **批准的实施计划**（与 Mint 自己的 [Helios Form](https://play.mint.gg/helios-form) 演示文稿使用的相同流程）。
---
## 成本模型
- 连接 MCP 端点是 **免费** 的（仅限 OAuth 登录）。
- 每次生成都会消耗 **积分** （付费计划，或试用/奖励/推荐注册时）。没有无限免费层。
- 无需本地 GPU 模型即可安装 — 完美的无头原型设计。
---
## 许可证
[MIT](LICENSE) © 2026 Celebez
