企业官网建设流程全解析

cli-anything-rekordbox：基于 SQLCipher 直写与虚拟 MIDI 的 Rekordbox 6/7 Agent 原生 CLI 实战指南

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

导读

Pioneer Rekordbox 6/7 没有提供任何面向回放控制的公开 REST/RPC API，这给“让 AI Agent 直接驱动 DJ 软件”带来了天然壁垒。本指南围绕 CLI-Anything 仓库中 rekordbox/agent-harness/REKORDBOX.md 展开，讲解如何用cli-anything-rekordbox这一 Agent 原生命令行工具，通过SQLCipher 加密数据库直写（pyrekordbox）+ 虚拟 MIDI（mido）两条通道，程序化完成曲库检索、播放列表写入（playlist create/add/clear）与双碟 live-deck 混音（play/sync/crossfade/EQ/hot-cue）。读完本文，你将掌握完整的安装、命令矩阵、写保护机制、JSON Agent 输出约定，以及从源码与测试层面理解其内部实现原理。

一、为什么需要这样一套 Harness：Pioneer 的三条程序化通道

Rekordbox 官方并未向开发者开放播放控制 API，其可编程面实际上只有三条：

1. master.db——SQLCipher 加密的 SQLite 曲库文件，包含曲目、播放列表、Cue、Hot Cue 等元数据；
2. 虚拟 MIDI——Rekordbox 接受任何已注册控制器映射发来的 MIDI 信号，可驱动播放、混音台等实时操作；
3. Pro DJ Link——面向硬件 CDJ 的只读网络广播，不提供写入能力。

cli-anything-rekordbox的定位正是把第 1、2 条通道组合进一个统一 CLI：曲库侧用pyrekordbox直接读写加密库（自动提取 Rekordbox 6/7 静态 master key），回放侧用虚拟 MIDI 发送器配合随包附带的Bunker.midi.csv控制器映射，最终以 JSON（--json，面向 Agent）或人类可读文本输出。这一点在 主 CLI 源码 docstring 中也有明确描述。

二、安装与前置条件

2.1 安装方式

pip install cli-anything-rekordbox # 可选的 Windows 扩展（用于 live-deck UI 自动化所需的 pyautogui/pywin32 等）： pip install cli-anything-rekordbox[windows]

从仓库的 setup.py 可以确认其运行时依赖为：

Python 要求>=3.10，且包声明了windows与dev（pytest）两个 extras。控制台入口cli-anything-rekordbox指向rekordbox_cli:main。

2.2 前置条件

• Python 3.10+；
• Rekordbox 6 或 7已安装，且master.db可被定位；
• 虚拟 MIDI 驱动（仅 live-deck 控制需要）：
  • Windows：loopMIDI、LoopBe 或 teVirtualMIDI；
  • macOS：IAC Driver（内置，通过“音频 MIDI 设置”启用）；
  • Linux：ALSA 虚拟 MIDI（snd-virmidi）。

注意：pyrekordbox会自动从rekordbox.exe中提取 Rekordbox 6/7 的静态 master key（所有安装实例共用同一把硬编码 AES-256 密钥），因此无需用户手动提供密钥。

三、快速开始

# 曲库巡检（无需 MIDI） cli-anything-rekordbox library count cli-anything-rekordbox library search "Daft Punk" # 创建并填充播放列表。写入前会先备份 master.db； # 若 Rekordbox 正在运行，除非加 --force 否则拒绝写入。 cli-anything-rekordbox playlist create "MyMix" cli-anything-rekordbox playlist add "MyMix" --track-title "Track A" cli-anything-rekordbox playlist add "MyMix" --track-title "Track B" # live-deck 混音（需要虚拟 MIDI 端口 + rekordbox 内启用映射） cli-anything-rekordbox install-mapping # 一次性：把 Bunker.midi.csv 放入 rekordbox MidiMappings/ cli-anything-rekordbox deck play --deck 1 --port "LoopBe" cli-anything-rekordbox deck crossfade 1 2 --secs 16 # 端到端：加载 + 混音两首曲目 cli-anything-rekordbox mix "Track A" "Track B" --secs 16 # REPL 模式 cli-anything-rekordbox

直接执行cli-anything-rekordbox（不带子命令）会进入 REPL：基于prompt_toolkit提供rekordbox>提示符，支持输入help查看命令帮助、exit/quit退出，见 rekordbox_cli.py。

四、命令组详解

4.1library：曲库巡检

从源码看，搜索与 info 输出字段包括id、title、artist、bpm（BPM/100.0，BPM 在库内以 100 倍整数存储）、genre/key（来自关联表的Name）、duration_ms（c.Length）与file（c.FolderPath），默认search上限为 20 条（--limit可调），见 library 实现。

4.2playlist：带写保护的播放列表写入

写保护语义（务必理解）：

• 每次播放列表写入前，CLI 会在master.db同级目录下创建cli-anything-backups/子目录，并以时间戳命名生成.bak备份（同时备份-wal与-shmsidecar 文件）；
• 若 Rekordbox 正在运行，默认拒绝写入；--force表示知晓风险，但仍然强制要求先备份；
• --no-backup只有在 Rekordbox 关闭时才被接受。

其底层逻辑集中在_open_db_for_write()：先做进程检测，再决定是否放行与备份，最终通过_commit_db_write()完成autoincrement_local_update_count、session.commit()与clear_buffer()，见 写保护实现。进程检测通过tasklist（Windows）/pgrep/ps（类 Unix）实现，也可用环境变量CLI_ANYTHING_REKORDBOX_RUNNING=1覆盖自动探测。

4.3deck：基于虚拟 MIDI 的 live-deck 控制

实现细节：命令通过_open_midi()在mido.get_output_names()中按子串（默认LoopBe）匹配并打开输出端口；按钮类消息用_tap()（note_on velocity 127 后延时约 30ms 再发 0），推子类消息用_cc14()构造 14-bit MSB/LSB 双 control_change（值域 0..16383）。例如 crossfade 会将 -1.0→+1.0 的推子位置线性插值到 14-bit 值，并通过_cc14(6, 0x1F, 0x3F, v14)发送，对应映射中的CrossFader（B61F），见 deck 实现。

4.4 顶层命令

install-mapping支持--rekordbox-dir显式指定，也会自动探测 Windows 的rekordbox 7.2.8/7.2.7/7.2.6/6.8.6安装路径与 macOS 的/Applications/rekordbox 7/.../MidiMappings。当目标目录存在时，会写入LoopBe Internal MIDI.midi.csv与Bunker.midi.csv两个名称，并把前者的 CSV@file头改写为匹配设备名（见 install_mapping）。

五、架构总览

+-----------------------------+ | cli-anything-rekordbox | +-----------------------------+ | +--------+----------+ | | v v +-----------+ +---------------+ | pyrekord- | | mido + | | box | | virtual MIDI | +-----------+ +---------------+ | | v v +----------+ +-----------------+ | master.db| | Rekordbox 6/7 | | SQLCipher| | (live decks) | +----------+ +-----------------+

两条数据通路彼此独立：曲库读写全部经过 pyrekordbox 解密master.db，不依赖 Rekordbox 前台运行（写入时除外）；实时回放则完全走 MIDI，由 Rekordbox 内部把映射信号映射到对应功能。该架构与 SKILL.md 中描述的“Agent → CLI → (pyrekordbox DB writes / mido+virtual MIDI)”调用链一致。

六、数据文件与 MIDI 映射

• Bunker.midi.csv——Pioneer 标准.midi.csv格式的控制器映射，覆盖浏览器导航（Browse/Forward/Back/Load）、碟机走带（PlayPause 900B、Cue 900C）、Sync/Master（9058/905C）、14-bit 推子（TempoSlider B000、ChannelFader B013、CrossFader B61F）、EQ（EQHigh B007/EQMid B00B/EQLow B00F）、每碟 8 个 Hot Cue（9000–9007，PadMode1）、Beat Loop、Beat Jump、PadMode 切换、Slip、Quantize 等。该文件由install-mapping直接投放到 rekordbox 的MidiMappings/目录，setup.py的package_data保证其随包分发。

七、JSON 输出约定（Agent 消费）

每个命令都支持--json：

$ cli-anything-rekordbox --json library search "Daft Punk" [{"id": 12345, "title": "One More Time", "artist": "Daft Punk", "bpm": 123.0}, ...]

输出由_emit()统一处理：开启--json时输出json.dumps(payload, indent=2)，否则 dict/list/标量分别渲染为人类可读文本。写入类命令还会在 payload 中附带backup（备份文件列表）、rekordbox_running、forced等安全字段，方便 Agent 感知写操作上下文（见 _emit）。

八、源码级验证：测试如何保证安全语义

仓库提供了一套冒烟测试 test_smoke.py，可运行pytest cli_anything/rekordbox/tests/复现，其核心断言与本文所述机制一一对应：

• --help与全部子命令--help退出码为 0（CLI 可解析性）；
• playlist create --help必须展示--force与--no-backup（写保护选项被正确公开）；
• 写保护拒绝：mock 进程检测为运行中且未加--force时，_open_db_for_write抛Refusing ...异常；
• 强制写仍需备份：运行中 +--force+--no-backup时抛without a backup；
• 备份先于写入：关闭状态下写入前会在cli-anything-backups/生成字节一致的.bak；
• 数据文件存在性：Bunker.midi.csv必须以@file,1,头随包存在。

此外，eval_pipeline.md 给出了需要真实 Rekordbox 环境的集成验收步骤（status期望非零 track_count、search "Demo"命中 Pioneer 演示曲、playlist 三连 create/add/clear、以及 MIDI 通路下deck eq --deck 1 --hi 0.5 --mid 0.5 --lo 0.5后观察 EQ 旋钮归中）。

九、注意事项与使用边界

• SQLCipher 密钥由 pyrekordbox 从rekordbox.exe自动提取，即 Rekordbox 6/7 各安装实例共用的静态 master key；
• 曲库写入默认要求 Rekordbox 关闭。--force属于显式承担风险的恢复/测试工作流，且必须先备份；
• live-deck 控制依赖一次性 UI 配置：在 RekordboxPreferences → Controller → MIDI中启用虚拟 MIDI 端口。本工具通过install-mapping+Bunker.midi.csv自动投放到正确目录，但仍需用户在偏好设置里启用该映射；
• Pioneer 不提供回放 REST API，因此这是“最接近官方能力”的程序化控制方案；mix命令当前会在曲库解析后提示需要先在 Rekordbox UI 中将两曲加载到碟 1/碟 2，再执行deck crossfade 1 2 --secs S。

十、License

MIT —— 与上层 CLI-Anything 项目保持一致（见 LICENSE）。

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything