renforge

RenForge

RenForge 是一款用于处理 Ren'Py 视觉小说项目的 MCP（模型上下文协议）服务、CLI 和 Web 控制面板。

它让 AI Agent（或通过控制面板操作的人类）能够检查项目、默认启用 Live Editor 启动游戏、选择并检查屏幕控件、在写入受保护的 .rpy 源文件前预览布局更改、操控运行时状态、截取屏幕截图、生成翻译、查找孤立资源、运行构建，以及搜索 Ren'Py 文档。

状态：alpha，正在积极开发。核心功能（MCP 工具、游戏内桥接、Live Editor、CLI、控制面板）均可正常使用；API 仍可能发生变化。

Live Editor — 选择可编辑控件、检查控件、预览移动效果，然后保存到源文件

控制面板 — 实时控制正在运行的游戏	Live Editor — 锁定的目标仍可检查，并附有清晰的原因说明
故事地图 — 点击节点即可跳转正在运行的游戏	资源审查 — 孤立文件、缺失文件、未定义图像

快速开始 — 控制面板

需要 Python 3.11+ 和 uv——除此之外无需安装其他内容。你甚至不需要安装 Ren'Py：RenForge 会复用在你的计算机上找到的 SDK，或者在首次启动时自动下载一个。

uvx --from "renforge[ui]@latest" renforge ui

然后，在控制面板的项目选择器中选择游戏——无需输入路径。（或者使用 --project /path/to/your/game 跳过选择器。）启动游戏，然后点击悬浮的 RF 控件打开 Live Editor。

实时编辑器

实时编辑器是 0.7 版的主打功能：在运行中的游戏内编辑符合条件的屏幕控件，在运行时预览布局更改，并且仅在目标通过源码安全检查时才保存。锁定或不受支持的目标仍可供检查，并会清楚说明原因——不会被强行修改。

适用对象	从这里开始
人工操作	控制面板或游戏窗口 → 启动 → 点击 RF → 从画布或场景树中选择 → 检查 / 移动可编辑项 → 保存 → 正常停止。
AI Agent	renforge_info（读取 live_editor）→ renforge_launch → 轮询 renforge_launch_status → renforge_screenshot / renforge_scene_tree → 使用受保护的 renforge_click_at 或 renforge_click_element → 验证 → renforge_stop。

完整的人工操作和 Agent 工作流、源码安全规则及截图： docs/LIVE_EDITOR.md。

安装

uvx 无需安装。如需在 PATH 中使用持久的 renforge 命令，请使用 pipx：

# Full install — MCP + CLI + web dashboard
pipx install "renforge[ui]"
renforge ui

# Slim install — MCP server + CLI only (no dashboard deps)
pipx install renforge
renforge serve

[ui] 会安装可选的控制面板组件（Starlette、uvicorn、watchfiles）。 如果只需要 MCP 服务或命令行，请跳过它。

在 Debian/Ubuntu 等受管理系统上，普通的 pip install 会被 PEP 668 阻止——请改用 uvx 或 pipx。

更新

安装方式	更新方法
uvx … @latest	无需操作——每次启动时，@latest 都会获取最新版本
pipx（完整或精简版）	pipx upgrade renforge
pip / venv	pip install -U "renforge[ui]"（精简版则使用 renforge）

更新内容：CHANGELOG.md · GitHub releases。

设置 MCP 服务（AI Agent）

所有客户端使用相同的服务命令：

uvx renforge@latest serve

每个 RenForge 工具都需要 project_path 参数，因此 Agent 会在每次调用时传入游戏路径——请原样复制以下配置，无需替换路径。

Claude Code

claude mcp add renforge -- uvx renforge@latest serve

Codex CLI

codex mcp add renforge -- uvx renforge@latest serve

Claude Desktop、Cursor、Windsurf、Cline、Gemini CLI——每个客户端的配置文件都使用相同的 mcpServers JSON 结构：

{
  "mcpServers": {
    "renforge": {
      "command": "uvx",
      "args": ["renforge@latest", "serve"]
    }
  }
}

客户端	配置文件
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	cline_mcp_settings.json
Gemini CLI	~/.gemini/settings.json

VS Code（Copilot）、Zed、Windows PATH 问题和 pipx 变体的说明，请参阅 MCP 指南。

验证是否正常运行——向 Agent 提问：

检查我位于 /path/to/game 的 Ren'Py 项目

Agent 应使用该路径调用 renforge_inspect_project，并返回项目的 JSON 摘要（标签、脚本、资源及相关元数据）。

功能

• 实时编辑器（启动时默认开启） — 在游戏中选择、检查和进行源代码安全预览/保存，可编辑控件；锁定的目标仍可检查。指南：docs/LIVE_EDITOR.md。
• 项目检查 — 汇总项目结构，扫描脚本/标签/资源，解析 lint 输出。
• 实时游戏控制 — 启动项目并注入游戏内桥接程序和实时编辑器，然后推进对话、列出/选择选项、计算表达式、获取/设置存储变量、发送针对当前焦点的文本/按键/滚动输入、轮询推送事件，并捕获模型能够直接看到的画面。
• 场景感知（像素级精确，无需视觉能力） — 将整帧读取为结构化的逻辑坐标节点（renforge_scene_tree）：包含每个精灵、控件和文本块的边界、z 顺序、颜色和样式，以及 ASCII 线框图和结构化场景差异。随后，renforge_measure 会以 Agent 可据以行动的数字报告对齐、间距、重叠、适配情况和 WCAG 对比度。
• 自动驾驶 — 在全新回放中，根据 Ren'Py 菜单的 items 自动选择并推进选项，包括自定义名称菜单和单项菜单，同时报告标签覆盖率和崩溃情况。目前不会自动探索未公开 Ren'Py 菜单 items 的自定义 call_screen 交互。
• 资源与翻译 — 查找未使用/缺失的图片和音频资源，列出语言，计算翻译统计数据，生成/更新 game/tl/<lang>/ 文件，并将对话导出为文本。
• 构建 — 打包桌面发行版和 Web 构建。
• 文档 — 搜索并阅读 Ren'Py 离线文档。
• Web 控制面板 — 实时故事地图、活动日志、自动驾驶覆盖率、lint 视图和游戏状态控制（默认地址为 127.0.0.1:8765）。

CLI

renforge --version
renforge inspect <project>      # lightweight project summary (JSON)
renforge serve [--project .]    # start the MCP server (stdio transport)
renforge ui [--project <project>] [--port 8765]  # start the web dashboard

文档

• 实时编辑器 — 面向用户和 Agent 的工作流、可编辑与锁定目标、源代码安全性、公开截图。
• MCP 指南 — 完整工具目录、Agent 工作流（实时编辑器、热重载、存档、像素级精确放置、场景感知）。
• 运行时策略 — 操作级风险强制执行与 MCP ToolAnnotations 的区别、授权及兼容性计划。
• 架构 — 代码布局、实时控制流程、Ren'Py SDK 解析、打包。
• 贡献指南 — 开发环境设置、前端构建、PR。
• 云端/CI 环境 — Cursor Cloud Agents、Xvfb、Ren'Py SDK 引导程序和环境冒烟测试。
• 更新日志 — 发行历史。
• examples/demo_game/ — 可用于体验所有功能的 Ren'Py 小型示例项目。

许可证

MIT

贡献者

特别感谢为 RenForge 作出贡献的人员：

• @AxelBeary — 完整的简体中文控制面板翻译及相关国际化修复。