m4l-project

M4L Project

此技能整合了 LLM 创建 Max for Live 设备时所需的实用规则。它不是一份详尽的参考资料，而是一份用于规避容易出错决策的检查清单。

基本方针

1. MUST：将生成脚本视为唯一可信源。.maxpat / .amxd 是生成产物；即使直接编辑，也必须将改动反映到生成脚本中。
2. MUST：为每个设备创建 packages/<device>/，并至少划分 devices/、scripts/、assets/、releases/、DESIGN.md、VERSION 和 LICENSE 的职责。
3. MUST：更改 UI 尺寸、颜色、边距、显示逻辑、MIDI 规格或同步规格时，记录到 packages/<device>/DESIGN.md。
4. SHOULD：将 Max patcher JSON 视为结构化数据，不要通过字符串替换来编辑。
5. NEVER：不要通过将 .maxpat 重命名为 .amxd 来创建 .amxd。
6. NEVER：不要只修改生成产物，导致它与生成源不一致。

Max for Live 生成

1. MUST：MIDI Effect 必须从 midiin / notein 输入，并通过 midiout / noteout 输出。
2. MUST：先确定设备类型是 Audio Effect、Instrument 还是 MIDI Effect，再让 I/O 与 .amxd type 相匹配。
3. MUST：MIDI Effect 的 .amxd 必须包含 FOURCC mmmm 和 project.amxdtype = 1835887981。
4. MUST：.maxpat 必须包含 openinpresentation: 1。
5. MUST：可见 UI 对象必须包含 presentation: 1 和整数类型的 presentation_rect。
6. MUST：所有可见 UI 对象必须满足 x + w <= devicewidth 且 y + h <= 169。
7. SHOULD：.amxd 使用图像、JS 或外部依赖时，应将依赖文件一并打包，使其能够独立加载。

UI / Presentation

1. MUST：Max for Live 设备的高度必须固定为 169px。
2. MUST：更改 UI 后，必须通过程序检查 Presentation 边界。
3. MUST：使用背景 panel 时，设置合适的层叠顺序，避免遮挡操作 UI。
4. SHOULD：live.* UI 应优先与 Live 主题保持一致，避免不必要地覆盖颜色。
5. SHOULD：固定尺寸的输入框、图标、画布和 Logo 应设置稳定的 presentation_rect，避免因数值变化导致布局移动。

JS / MIDI 逻辑

1. MUST：显示上的点判定与发声判定必须使用同一个函数，或从相同数据推导而来。
2. MUST：保持 Note On 与 Note Off 的对应关系。
3. MUST：规格要求使用输入 MIDI 时，没有输入时不得擅自回退并播放音符。
4. MUST：Random 的目标仅限于规格明确指定的值。
5. MUST：规格要求“仅在命中瞬间发声”时，必须加入边沿判定，避免在同一命中范围内持续触发期间重复发声。
6. SHOULD：Max JS 函数名应能体现其与 Max 消息名之间的对应关系。
7. SHOULD：将 JS Task 视为低优先级事件；对于 Freeze/Export 中需要精确 MIDI 时序的处理，应谨慎使用。

Transport / Freeze / Export

1. MUST：不得将 Live API（live.object、live.observer、LiveAPI）用作发声时钟。Live API 优先级较低且为异步机制，不应将其视为 Freeze/Export 期间可靠的时序源。
2. SHOULD：需要 Transport 同步时，应使用 Max 侧与 Live transport 同步的机制，例如 Max 的 transport/tempo-relative clock。
3. MUST：重负载导致 scheduler tick 跳过时，不得实现将过去的事件集中到当前时刻发声的追赶逻辑。应丢弃延迟的过去音符，或将其设为明确指定的独立模式。
4. MUST：即使相同的 transport 位置、degree 和 tick 多次出现，也不得重复触发同一事件。
5. SHOULD：如果 Freeze/Export 出现问题，应考虑改用 Max 标准对象（makenote、pipe、flush、midiformat 等），而不是使用 JS 内部的发声调度。

AMXD / Packaging

1. MUST：写出 .amxd 二进制容器时，生成后至少要检查其中包含预期的 .maxpat / JS / 图像名称。
2. MUST：依赖文件的 dependency_cache 必须使用可在分发环境中解析的路径。不得依赖本地绝对路径。
3. MUST：发布产物必须包含 VERSION、LICENSE、.amxd、.maxpat、JS 和引用图像。
4. SHOULD：安装到 Ableton User Library 时，先删除同名旧文件，再复制新的 .amxd。
5. MUST：向用户提交最终报告时，如果需要在现有 Live 实例中重新插入设备，必须明确说明。

验证

1. MUST：修改 JS 后，运行 node --check <device>.js。
2. SHOULD：修改 Python 生成脚本后，运行 python3 -m py_compile <script>.py。
3. SHOULD：生成后，检查 .maxpat 的 Presentation 边界和 patchline 端点。
4. SHOULD：生成 .amxd 后，检查设备类型、打包的依赖项和主要 JS 字符串是否包含在其中。
5. SHOULD：需要确认 Live 中的行为时，检查 Max Console / Open Max Window 是否有错误。

已精简旧技能的处理方式

旧结构将 overview、maxpat format、amxd conversion、presentation layout、live api、javascript、gen、debugging 和 py2max 分为不同技能。但在实际工作中，所需判断被拆散，存在受局部知识影响而将 Live API 用作时钟等风险。

今后以此整合技能为入口，并在需要时再单独查阅详细的官方文档或现有实现。