一个命令行工具包，让 AI 帮你把 RPG Maker（RM）游戏翻译成中文。
你不需要懂编程，也不需要自己判断游戏引擎或原文语言。告诉 AI 你的游戏在哪，它会先检查，再带你完成汉化。
得益于 2026 年 Agent 工具和 AI 模型能力的大爆发，项目得以迅速迭代。但个人精力有限，快速迭代下不可避免地只能关注最终目的，以及如何更好地达成目的，无暇顾及每一个实现细节。这必然会带来一些未知的潜在问题——现实世界的复杂性是无穷大的。所以你的反馈体验极为重要，请不要吝惜 Issue，我会听取每一个 Issue，继续打磨迭代项目。
⚠️ 目前仅支持 RPG Maker MV / MZ 游戏。 后续支持 XP、VX、VX Ace 等 RGSS 系列引擎需要新增归档解包、Ruby Marshal 反序列化和 Ruby / RGSS 脚本解析等适配层。如果你有需求，去 GitHub ⭐ 点个 Star 或提个 Issue，给作者一点更新的动力。
| 功能 | 说明 |
|---|---|
| 🧵 高并发翻译 | 可配置的并发数量和请求速率，大批量文本也能快速跑完 |
| ⚡ 大游戏更省等待 | 翻译、检查和写入这些耗时步骤都按大项目优化，文本很多也不用一直卡着 |
| 💾 译文持久化缓存 | 中断后重新运行自动跳过已翻译内容，不重复工作，不重复花钱 |
| 🔄 运行时去重 | 同一轮内出现多次的相同原文只翻译一次，结果自动复用到所有位置 |
| 🛡️ 细粒度失败处理 | 翻译出错不会整批丢弃，单条失败不影响同批其他成功条目，重试、标记、分类逐级收窄 |
| 🔧 全角引号自修复 | 模型可能把日文「」改写成中文""或英文""，工具会自动还原为源文标点字符 |
| 📜 剧本化翻译上下文 | 按地图场景和角色对话组织翻译内容，模型看到的是带上下文的剧本而非散装文本 |
| 📚 引擎级术语表 | 从游戏数据自动提取角色名、技能名等术语候选，Agent 填写后注入翻译流程，确保术语前后一致 |
| 🔒 语义化占位符 | 游戏控制符在翻译时被替换为可读标记，模型只翻译文字不碰控制符，翻译后精确还原 |
| ✏️ 自定义占位符 | 游戏自带的特殊标记可以由 Agent 分析后自行定义保护规则 |
| ✅ 翻译格式检查 | 逐条检查漏翻、控制符破坏、源文残留、行宽超标等问题，生成可定位的质量报告 |
| 🤖 Agent 自主分析工作流 | 插件参数、事件指令、Note 标签中哪些文本该翻译、哪些不该碰，全部由 Agent 自主判断并写成规则 |
三样东西：
- 🤖 一个能执行命令的现代 AI Agent — 你的 AI 助手
- 📦 A.T.T MZ 发行包 — 翻译工具
- 🔑 一个大模型 API Key — 翻译引擎的"钥匙"
需要能执行命令、读写文件、处理多步骤任务的 Agent。下面这些入口适合新手优先尝试，实际可用能力以各产品当前版本为准：
| Agent | 形式 | 说明 |
|---|---|---|
| Codex 桌面版 | 🖥️ 桌面应用 | 适合直接打开游戏目录，让 Agent 按 Skill 连续执行 |
| 腾讯 WorkBuddy | 🖥️ 桌面应用 | 面向多步骤任务和多 Agent 协作的工作台 |
| 阿里 Qoder | 🖥️ 桌面 / 编程平台 | 面向真实工程任务的智能编程平台 |
| 智谱 ZCode | 🖥️ 桌面应用 | 面向长任务的智能体开发环境 |
| OpenCode Windows 桌面端 | 🖥️ 桌面应用 | 开源 AI 编程 Agent，下载页提供 Windows x64 桌面版 |
选择你顺手的即可。如果 Agent 支持子代理，术语、规则和质量审查可以并行推进；不支持子代理时，也能按 Skill 串行完成。
建议给 Agent 本身 选择较强的模型，例如 GPT-5.5 或同等级模型。A.T.T MZ 的工作流很吃模型编排能力、长上下文能力、工具调用能力和指令遵循能力；Agent 模型太弱时，常见问题不是翻译质量差一点，而是跳过 Skill、误改文件、漏跑检查或把未完成结果当成完成。
setting.toml 里的底层翻译模型主要负责批量翻译正文，够用即可，不必为了流程稳定性盲目堆最强模型。真正决定工作流是否稳的是你正在对话、开目录、执行命令的 Agent 模型。
如果发现 Agent 的动作不对，第一时间让它自检：
请先停止当前动作，说明你是否正在严格遵循 A.T.T MZ 的 Skill。请引用 Skill 中当前阶段的通过标准、硬停止规则和下一步命令，再继续执行。
怎么算装好了？在对话框里输入"你好"，AI 回复你了就说明 OK。
💡 下面教程以 Codex 桌面版 为例。用其他 Agent 时也一样：先打开游戏目录，再把 A.T.T MZ 工具包路径和提示词发给 Agent。
- 打开 GitHub Releases，按运行环境下载发行包：
- Windows x86_64：
att-mz-windows-x86_64.zip - Linux / WSL x86_64：
att-mz-linux-x86_64.zip
- Windows x86_64：
- 解压到你方便找的位置。Windows 可右键 zip → 全部解压缩；Linux / WSL 可执行
unzip att-mz-linux-x86_64.zip，如果权限丢失再执行chmod +x att-mz/att-mz - 用文本编辑器打开解压出来的
setting.toml，填模型配置：
[llm]
default_client = "main"
[[llm.clients]]
name = "main"
provider_type = "openai"
base_url = "https://你的服务商地址/v1"
api_key = "你的API Key"
model = "模型名称"
timeout = 600- 保存、关闭
provider_type 目前填 openai，表示 OpenAI 兼容接口。base_url、api_key、model 这三个值你的 API 服务商会提供。常用的服务商有阿里云百炼、DeepSeek、硅基流动、OpenRouter 等。不知道填什么的话，直接问你的 Agent：「我的 API 服务商是 xxx，帮我填好 A.T.T MZ 的模型配置」。
如果想准备多个模型客户端，继续追加 [[llm.clients]] 并使用不同 name。执行翻译时可让 Agent 给 doctor、translate 或 run-all 加 --llm-client <客户端名称> 选择；模型名、超时、地址和 Key 都写在对应客户端配置里。
Linux / WSL 发行包可以原生运行 A.T.T MZ CLI，并能处理 /mnt/c/... 这类 WSL 挂载路径下的游戏目录。RPG Maker MV/MZ 的 Windows 游戏本体通常仍通过 Game.exe 启动，试玩和效果确认建议回到 Windows 环境进行。
💡 如果你习惯用源码运行，看仓库里的 进阶教学与源码编译。普通使用不需要。
用 Agent 打开你的游戏目录。游戏目录是你要翻译的项目——里面有游戏数据、剧情文本、插件脚本。A.T.T MZ 是外部工具，以命令行方式被 Agent 调用。
操作：在 Agent 中点击"打开文件夹"，选择你的游戏目录。
根据你使用的是发行包还是源码运行，复制下面其中一段给 Agent。把尖括号里的内容换成你自己的路径或游戏名，不要把 API Key 发进对话。
适合下载 Windows 或 Linux / WSL 发行包后直接使用的人。
请使用 A.T.T MZ 工具包（发行包目录：<A.T.T MZ 发行包目录>）按照发行包内 `skills/att-mz/SKILL.md` 的流程，对当前打开的 RPG Maker MV/MZ 游戏进行完整汉化。
允许使用子代理协助分析术语、规则和质量问题；允许在我确认后使用字体替换技术将中文写入游戏文件。工作过程中请持续记录使用体验、异常、命令结果和流程问题，完成后输出体验文档，供后续优化参考。
重要约束：只能通过 A.T.T MZ CLI 和 Skill 规定的合法流程处理游戏；禁止手改游戏 `data/*.json`、插件源码、译文数据库或工具包文件。遇到技术阻碍且判断属于工具源码问题时，立即停止并向我汇报，不要自行修改源码。
适合你从仓库源码运行，或正在参与工具包开发的人。
请使用 A.T.T MZ 源码工具包（源码目录：<A.T.T MZ 源码目录>）按照 `skills/att-mz/SKILL.md` 的流程，对当前打开的 RPG Maker MV/MZ 游戏进行完整汉化。默认命令使用 `uv run python main.py <命令>`。
允许使用子代理协助工作；允许在我确认后使用字体替换技术将中文写入游戏文件。如有必要，可以编写只读脚本读取工具包数据库内容用于排查，但严格禁止修改数据库结构或数据。
工作执行过程中，请持续收集使用体验、异常、命令结果和流程问题，最终输出详细体验文档，为后续优化工作提供参考依据。
重要约束：如果遇到技术阻碍且确定属于工具源码问题，必须立即停止当前汉化流程并向我汇报；严禁任何形式的源码修改操作。确保整个汉化过程不触及游戏核心代码，仅通过工具包提供的合法途径完成汉化任务。
Agent 收到任务后，会自己完成整个流程：
- 🔍 识别游戏引擎（RPG Maker MV 或 MZ）
- 🌐 判断原文语言（日文或英文）
- 📝 注册游戏、导出文本、分析规则
- ⚡ 大型游戏会建立文本范围索引，后续小批翻译、手动补译和质量检查不必每次全量扫描
- 🤖 调用模型翻译正文
- ✅ 检查翻译质量
- 💾 确认没问题后把译文写进游戏文件
过程中 Agent 会一步步向你报告进度。遇到需要确认的事情（比如要不要换游戏字体），它会主动问你。你只需要回答"可以"或"不行"。
如果 Agent 说需要重建文本索引、重新准备工作区或重建当前运行文件，让它按 Skill 和 CLI 输出继续处理即可。新手不需要记命令，关键是不要绕过工具去手改游戏文件。
AI 把译文写进游戏文件后，打开游戏实际玩一遍。如果发现：
- 👀 有文字还是日文/英文（漏翻）
- 💬 翻译不通顺或意思不对（误翻）
- 📏 文字太长显示不全（显示问题）
直接在 Agent 对话框里说：
游戏里 NPC "老爷爷" 说的话还是日文，帮我查一下
物品说明栏里的文字太长了，显示不全
Agent 会定位问题、修复译文、重新写进游戏。试玩 → 反馈 → 修复，这个循环可以反复进行，直到你满意为止。
直接问 Agent。 任何关于本项目的问题——配置报错、翻译卡住、游戏跑不起来——全部问它。Agent 读了项目说明和 Skill，比你自己翻 FAQ 快得多。
打开对话框，直接问。