Universal Modder 安装与使用教程

环境要求

一次装好所有依赖

winget install Git.Git Python.Python.3.12 astral-sh.uv Gyan.FFmpeg
winget install BlenderFoundation.Blender   # 可选，用于 3D → 精灵图

brew install git python ffmpeg uv
brew install --cask blender                 # 可选

sudo apt install git python3 python3-venv ffmpeg
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows、macOS 和 Linux：各自能用什么

工具包大部分是跨平台的。负责操控运行中游戏的部分（启动、截图、输入、只录游戏声音的窗口录制）以 Windows 为主，因为游戏基本都在 Windows 上。Agent 可以原生或通过 WSL2 操控 Windows 游戏。

在 macOS 和 Linux 上，Agent 仍可用系统自带的截图录屏工具（screencapture、ffmpeg、xdotool）在游戏里测试，只是没有预先配好。知识库里有在 Linux 上跑 xEdit、在 macOS 上用 Wine 跑 HL2 的笔记，说明这是可行的。

按 Agent 安装：并排对照

每种方式安装的都是同样的技能（Agent Skills 格式）、fal MCP 服务和 um 命令行。

Claude Code

在 Claude Code 会话里运行（不是在终端里）：

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

选择 user 作用域，这样在任何文件夹都能用；如果提示，再运行 /reload-plugins。完整步骤（包括 Claude Desktop 以及如何调用每个技能）见 Universal Modder + Claude Code 页面。

OpenAI Codex

codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder

Codex 从 .agents/skills 读取技能，从 .codex/config.toml 读取 MCP 配置。

Gemini CLI

gemini extensions install https://github.com/rehan-remade/universal-modder

扩展清单是 gemini-extension.json；指令来自 GEMINI.md，它指向 AGENTS.md。

VS Code + GitHub Copilot

1. 打开设置，开启 chat.plugins.enabled。
2. 打开命令面板，运行 Chat: Install Plugin From Source。
3. 粘贴 https://github.com/rehan-remade/universal-modder。

MCP 配置位于 .vscode/mcp.json。

Cursor

从 Cursor Marketplace 安装，或克隆仓库后打开：Cursor 会自动读取 AGENTS.md 和 .cursor/mcp.json。

OpenCode

git clone https://github.com/rehan-remade/universal-modder
cd universal-modder
opencode

opencode.json 会加载技能和 fal MCP 服务。

其他任何 Agent

# 只装技能，放进 Agent 的技能目录
npx skills add https://github.com/rehan-remade/universal-modder

# 或者整个仓库：在克隆目录里启动你的 Agent
git clone https://github.com/rehan-remade/universal-modder

单独安装 um 命令行

插件安装和克隆仓库都会自动把 um 加到 PATH。如果你在别处使用技能，或想在普通终端里用 um，把它当作工具安装即可。它从 GitHub 安装，不在 PyPI 上，所以 pip install universal-modder 是装不上的。

uv tool install git+https://github.com/rehan-remade/universal-modder
# 或
pipx install git+https://github.com/rehan-remade/universal-modder

每个命令组都有带示例的 --help。参见 um 命令参考。

设置 fal API 密钥

在 fal.ai/dashboard/keys 获取密钥（需要先充值；密钥只显示一次，记得保存）。fal MCP 服务和 um fal 都靠它工作。

export FAL_KEY="your-key"
# 永久生效
echo 'export FAL_KEY="your-key"' >> ~/.zshrc   # 或 ~/.bashrc

setx FAL_KEY "your-key"
# 然后打开新终端并重启 Agent

没有密钥？um comfy 可以用本地 ComfyUI 生成图片。音频、3D 和视频仍需要 fal。价格见费用页。

检查安装

um --help
um kb search "terraria"       # 查已有实战笔记（在仓库外也能用）
um scan --list                # 本机找到的游戏
um fal price fal-ai/trellis-2 # 确认 FAL_KEY 可用

第一次使用：一个可回退的小改动

1. 选一个容易上手的游戏有成熟加载器的游戏最友好：Terraria（tModLoader）、星露谷物语（SMAPI）、Minecraft（Fabric/Forge）、用 BepInEx 的 Unity 游戏、用 UE4SS 的虚幻游戏。查看游戏库。
2. 先让它侦察
   提示词复制

   我这份 Terraria 是什么引擎？有人改过吗（查一下知识库）？你会走哪条路线？先不要改任何东西。

3. 让它备份并搭建实验环境Agent 会用 um backup create 给存档做快照，使用单独的配置或世界，并在安装加载器前先问你。
4. 先做通一个切片
   提示词复制

   加一把回旋镖：在敌人之间弹跳四次后返回。先用占位精灵图，在游戏里能用之后再用 fal 生成正式精灵图。

5. 验证，再扩展启动游戏亲眼看一下，再提更多需求。长期项目记录在 MODLOG.md 里；新会话里告诉它“读 MODLOG.md 然后继续”。

常见问题排查

添加 marketplace 时报 Git / SSH 错误

插件市场是用 Git 克隆的。如果你的电脑没有 GitHub SSH 密钥，让 Git 对 GitHub 改用 HTTPS：

git config --global url."https://github.com/".insteadOf git@github.com:

安装后看不到技能

运行 /reload-plugins（Claude Code）或重启 Agent，并在 /plugin 里确认插件已启用。

um: command not found

插件安装后打开一个新终端，或按上面的方法用 uv tool install 安装命令行，并确保 ~/.local/bin 在 PATH 里（uv tool update-shell）。

um fal 提示缺少密钥

FAL_KEY 必须设置在启动 Agent 的那个环境里。setx 或修改 shell 配置后要重启 Agent。

um win 拒绝运行

它只能在 Windows 或 WSL2 上操控 Windows 游戏。在 macOS/Linux 上请手动在游戏里测试。