att-mz

# A.T.T MZ Skill 本 Skill 是翻译任务执行协议，不是项目说明书。主文件只描述阶段、边界、必读参考资料和停止条件；命令细节、JSON 结构、样例、任务单和失败恢复都按阶段读取 `references/`。 ## 核心原则 - 业务数据只通过 A.T.T MZ CLI、工作区 JSON、当前游戏目录和用户明确提供的信息流转。 - 任何会消耗模型额度、导入规则、保存译文或写进游戏文件的动作，都必须先满足当前阶段的通过标准。 - 对用户报告时，把内部状态、字段名和命令结果转成业务影响与下一步动作；只有排障或解释 JSON 结构时才保留原字段名。 - 第一次写进游戏文件只表示生成第一版可试玩汉化结果，稳定版本依赖用户试玩反馈继续补漏。 ## 运行边界 - `<项目目录>` 是 A.T.T MZ 源码仓库。开发版默认命令是 `uv run python main.py --agent-mode <命令> ...`。 - `<游戏目录>` 是目标 RPG Maker MV/MZ 游戏目录。首次注册必须使用没有 `data_origin`、`js/plugins_origin.js` 和 `js/plugins_source_origin` 的干净原始目录；注册游戏时由 CLI 创建这组可信源快照。 - `<工作区>` 是任务临时目录。导出文件、规则草稿、任务包、临时脚本和手动填写译文表都放在这里，不能散落到项目目录或游戏根目录。 - 模型地址、API Key、路径、业务参数和可调开关只从环境变量、本地配置或 CLI 参数读取，不写进任务文件、报告或提交。 - 首次执行阶段命令时，业务参数和可调开关默认使用 `setting.toml` 与本地配置；只有命令必需定位参数、用户明确指定值、CLI 契约要求显式传入，或默认配置已被 CLI 输出证明不适合当前阶段时，才用环境变量或 CLI 参数做最小覆盖，并在报告中说明原因。 - 所有工作区 JSON、规则文件、临时脚本和报告按 UTF-8 读写。终端乱码或控制符边界异常时，先核验原始字符，再继续导入、翻译或写回。 - `--json` 命令的 stdout 只读取最终 JSON；长任务的 stderr 进度行是阶段进展，不是结果 JSON。 - 长任务先沿用 `setting.toml` 与当前环境中的线程配置；如果默认配置导致吞吐明显不足、CLI 输出提示线程配置不合适、用户要求性能优先，或当前机器是专用运行机器，再把 `ATT_MZ_RUST_THREADS` 设为合适的逻辑处理器数量。不要把 `4` 当上限；`4` 只用于可重复性能验收基线。 ## 按需参考资料 | 主要工作 | 必读参考资料 | 读取时机 | | --- | --- | --- | | 命令调用与成功判断 | `references/cli-command-contract.md` | 运行或排查任一 CLI 阶段前 | | 工作区文件与 JSON 结构 | `references/workspace-schema.md` | 读取、填写或修复工作区 JSON 前 | | RPG Maker MV/MZ 常识 | `references/rpg-maker-mv-mz-world-knowledge.md` | 判断引擎协议、事件指令、数据库字段、插件和 Note 标签语义时 | | MV 虚拟名字框 | `references/mv-virtual-namebox-rules.md` | MV 游戏第零...