宏录制回放与自动弹琴

宏录制回放用于记录并重新执行游戏操作；自动弹琴提供将 MIDI 乐谱转换为奇想盒脚本的能力。以下内容严格限定于本次提供的项目说明能够证实的功能边界；具体实现、接口和脚本格式尚无可核验的源码材料。

目的与范围

本页聚焦项目说明中列出的两项游戏自动化能力：录制操作和播放操作，以及 MIDI 乐谱转奇想盒脚本。说明中明确指出宏不支持视角转动的操作，这是制作和复用宏时需要优先考虑的限制。

自动跑图的路线录制、编辑和执行是另一项功能；虽然项目结构说明把自动跑图和宏的脚本仓库都列在 scripts/，不能因此将路线录制等同于宏录制。每日任务、自动对话和 AI 对话也不属于本页的实现范围。有关这些功能，应参阅各自的专题。

概览与已确认的边界

能力	项目说明明确确认的行为	尚未确认的细节
宏录制	录制操作	可录制的具体键鼠事件、录制触发方式、时间戳精度和脚本格式。
宏回放	播放操作	回放调度、速度、暂停、取消、异常恢复和重复执行策略。
视角转动	宏不支持视角转动的操作	不支持的技术原因，以及是否存在其他能力可以替代。
自动弹琴	MIDI 乐谱转奇想盒脚本	MIDI 解析器、音符映射、节拍与延音处理、脚本执行入口及支持的游戏乐器。
脚本位置	项目结构描述 `scripts/` 为自动跑图和宏的脚本仓库	宏脚本的目录层级、命名约定，以及转换后的弹琴脚本是否存放于同一目录。

上述区分很重要：“转换为脚本”不等同于已证实会立即在游戏中演奏。目前仅能确认项目说明所列的转换功能，不能推断转换后的运行流程。

架构与集成范围

项目说明把奇想盒定位为后端：通过奇想盒 app 运行，后端负责 RPC 服务、大模型调用和工具调用，不再提供 UI 界面。项目结构说明列出了 whimbox/rpc_server.py、whimbox/interaction/、whimbox/task/ 及 scripts/ 等位置，并将 scripts/ 描述为自动跑图和宏的脚本仓库。但提供的材料没有这些文件的内容，无法验证宏或 MIDI 功能调用了哪些模块，也无法确认具体的 RPC 路由和依赖关系。因此不画未经源码核实的组件连线图。

与游戏交互的项目级约束是：项目声明通过截图和模拟鼠标键盘工作，不修改游戏文件，也不读写游戏内存。这描述的是项目整体的交互方式，不能据此反推出宏录制所采用的事件捕获 API、弹琴回放的时序算法或具体的数据路径。

宏录制与回放

从用户可见功能看，宏有两个阶段：先录制操作，再播放操作。项目说明没有给出录制的开始和结束条件、录制结果如何保存、如何选择宏、是否允许编辑及如何处理回放期间的人工输入。因此目前不能提供可执行的操作步骤、事件格式或 API 签名。

视角限制

项目说明直接将“不支持视角转动的操作”写在宏功能描述中。设计需要视角变化的宏时，不应假定视角转动能被记录或准确重放；同样，不能在缺少实现证据时承诺通过其他输入方式绕过这一限制。自动跑图另有路线录制与执行能力，但项目说明没有建立两者之间的调用或兼容关系。

脚本存放与生命周期

项目结构示意将 scripts/ 标为“自动跑图和宏的脚本仓库”，这说明宏与自动跑图共享一个脚本存放概念，而不是说明它们使用相同格式。尚未获得脚本读写实现、样例脚本及目录中的实际文件；无法确定宏如何序列化、版本兼容如何处理、保存是否为原子操作或执行后是否清理临时文件。

自动弹琴与 MIDI 转换

已明确的能力是“MIDI 乐谱转奇想盒脚本”。其输入在功能说明中称为 MIDI 乐谱，输出称为奇想盒脚本。有关 MIDI 轨道、和弦、速度事件、音域、音符到按键的映射以及生成脚本的执行方法，现有材料没有实现证据，不应把它们当作已经支持的功能或约束。

特别注意：“自动弹琴”是项目给出的功能名称；当前资料能够直接确认的具体步骤只有 MIDI 到脚本的转换。脚本如何被调用、是否与宏回放共用执行器、是否要求游戏处于特定界面，均需检查实际实现才能确定。

运行环境与操作注意事项

项目说明称奇想盒 2.0 应通过奇想盒 app 运行，当前项目是后端而非独立 UI。它也指出项目仅支持 Python 3.12，游戏目前仅支持标准 16:9 分辨率运行；截图和图像识别会增加 PC 性能开销，因此目前仅支持中高配 PC。这里的运行限制来自项目整体说明，并非已经验证为 MIDI 转换自身的要求。

项目说明明确提醒：虽然项目不修改游戏文件、不读写游戏内存，但并不保证不会因使用受到游戏条款约束；使用后果由使用者承担。宏回放和自动弹琴均属于会影响游戏操作的能力，使用时应遵循这一项目级提醒。

接口、配置与代码示例

No code example available. 本次提供的是项目说明文字及目录示意，没有宏录制、回放或 MIDI 转换的源码、测试和真实调用示例；因此不能安全提供可执行代码片段、命令、脚本样例、配置项默认值或 API 参数表。项目说明没有列出这两项能力的专用配置键或 RPC 方法名。也无法建立符合要求的源码行链接，因为运行时未提供文件引用基础 URL。

故障边界与待核实事项

**录制内容不完整：**已知视角转动不受支持；其他事件的捕获范围和失败提示未见实现材料。
**回放偏差或中断：**没有可核验的定时、窗口焦点检查、游戏状态检查、重试、取消或恢复逻辑；不要假定系统会自动纠正回放结果。
**MIDI 不可转换：**没有可核验的文件格式校验、音域处理、错误类型或异常反馈机制。
**并发执行：**没有关于多个宏同时运行、录制与回放同时发生或弹琴与其他任务竞争输入的实现资料，不能承诺互斥或并发安全。
**持久化与测试：**目录示意指向 scripts/，但未提供目录实际内容、写入逻辑或测试用例，无法确认数据格式、迁移策略与测试覆盖范围。

后续若要补全工程级参考，应核对实际录制器、播放器、MIDI 转换器、脚本读写、RPC 暴露方式及相关测试，再补充经源码验证的调用链、时序图和带行号的示例；在此之前不宜将这些待核实项描述为已实现设计。