内容
# RenForge
RenForge 是一个 **MCP（模型上下文协议）服务器、命令行界面（CLI）和网页仪表盘**，用于处理 [Ren'Py](https://www.renpy.org/) 视觉小说项目。
它允许 AI 代理或通过仪表盘的人类检查项目，启动和驱动正在运行的游戏，读取/写入游戏状态，捕获截图，生成翻译，找到孤立的资产，运行构建和搜索 Ren'Py 文档。
> 状态：**alpha**，正在积极开发中。核心表面（MCP 工具、游戏内桥接、CLI、仪表盘）功能齐全；API 可能会发生变化。
## 功能
- **项目检查** — 总结结构，扫描脚本/标签/资产，解析 lint 输出。
- **实时游戏控制** — 启动具有注入的游戏内桥接的项目，然后推进对话，列出/选择选项，评估表达式，获取/设置存储变量，轮询推送事件，并捕获模型可以看到的帧。
- **自动驾驶** — 自动播放游戏，跨分支报告标签覆盖率和崩溃。
- **资产和翻译** — 查找孤立/缺失的图像和音频资产，列出语言，计算翻译统计数据，生成/更新 `game/tl/<lang>/` 文件，导出对话为文本。
- **构建** — 打包桌面发行版和网页构建。
- **文档** — 搜索和阅读 Ren'Py 的离线文档。
- **网页仪表盘** — 使用 Starlette + WebSocket UI，具有实时故事地图，活动日志，自动驾驶覆盖率，lint 视图和游戏状态控制。
## 安装（开发）
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[fastmcp]" # 完整的 MCP 运行时（fastmcp）
pip install -e ".[ui]" # 仪表盘（starlette，uvicorn，watchfiles）
pip install -e ".[test]" # pytest
```
基本安装只需要 `mcp>=1.0.0`；如果未安装 `fastmcp`，服务器将回退到兼容模式，并显示清晰的消息。
## 使用
### 命令行界面
```bash
renforge --version
renforge inspect <project> # 轻量级项目摘要（JSON）
renforge serve [--project .] # 启动 MCP 服务器（stdio 传输）
renforge ui --project <project> [--port 8765] # 启动网页仪表盘
```
### MCP 服务器
`renforge serve` 向任何 MCP 客户端公开以下工具。子集：
- `renforge_inspect_project`，`renforge_scan_project`，`renforge_parse_lint`
- `renforge_launch`，`renforge_stop`
- `renforge_game_state`，`renforge_advance`，`renforge_list_choices`，
`renforge_select_choice`，`renforge_eval`，`renforge_get_var`，
`renforge_set_var`，`renforge_poll_events`，`renforge_screenshot`
- `renforge_autopilot`
- `renforge_assets`，`renforge_languages`，`renforge_translation_stats`，
`renforge_generate_translations`，`renforge_export_dialogue`
- `renforge_web_build`，`renforge_distribute`
- `renforge_search_docs`，`renforge_get_doc`，`renforge_list_docs`
### 实时控制
`renforge_launch` 将桥接注入到 `<project>/game/`（在拆除时删除）并启动游戏。实时工具需要显示 — 在 WSLg 下直接工作；无头 CI 应使用 `xvfb-run` 包装调用。
### 网页仪表盘
`renforge ui --project <project>` 提供一个仪表盘（默认 `127.0.0.1:8765`），具有故事地图，活动日志，自动驾驶覆盖率，lint 视图和实时游戏控制，支持 WebSocket。
## 示例
一个小型示例项目位于 `examples/demo_game/` 中。
## 架构
```
src/renforge/
cli.py # argparse 入口点（inspect / serve / ui）
server.py # MCP 应用启动 + 回退 + 工具注册
bridge/ # 游戏内 .rpy 桥接，启动器和客户端
tools/
live.py # 运行游戏控制（启动，评估，截图，...）
project_ops.py # 资产，翻译，构建，文档
static.py # 检查 / 扫描 / 解析-lint
ui/ # Starlette 仪表盘（服务器，ws，图，活动，轮询器）
util/ # 文件系统 + 子进程助手
sdk.py # Ren'Py SDK 下载/缓存
scanner.py # 脚本/标签/资产扫描
lint.py # lint 运行器 + 解析
autopilot.py # 分支自动播放 + 覆盖率
translation.py # 翻译生成/统计
```
打包使用 `hatchling`；控制台脚本是 `renforge = renforge.cli:main`。
## 许可证
MIT
