内容
<p align="center">
<img src="Beat-Twin_logo.png" alt="Beat Twin logo" width="240">
</p>
# 拍子双胞胎
拍子双胞胎是一个概念验证桥，连接Bitwig Studio和模型上下文协议（MCP）。
它公开了一个小型本地MCP服务器，用于代理辅助音乐工作流程，同时将DAW突变保持在显式写入策略门后。默认模式是只读。
## 功能
- 只读会话检查，适用于传输、轨道、场景、选定设备和远程控制。
- 基于当前只读Bitwig快照的仅计划安排建议。
- 传输、混音器、剪辑、场景、设备和应用程序的写入工具，默认隐藏和阻止。
- 一个Bitwig控制器脚本，通过本地TCP连接使用JSON-RPC进行通信。
- 离线协议和策略测试，无需启动Bitwig。
- 一个浏览器Playground，用于命令优先的歌曲草图、Tone.js试听、音符编辑、模式工具、键盘快捷键、本地撤销/重做、JSON保存/加载、可见的时间线反馈、本地命令调色板和确定性命令草图。
## 架构
```text
MCP 客户端
-> Node.js MCP 服务器（index.js）
-> 本地 TCP JSON-RPC 桥（127.0.0.1:8888）
-> Bitwig 控制器脚本
-> Bitwig Studio
```
Node.js 进程是 MCP 服务器。它根据需要通过 `BITWIG_HOST` 和 `BITWIG_PORT` 连接到 Bitwig 控制器。
基于浏览器的 Playground 基础现在与 MCP 桥一起存在：
```text
应用/Playground
-> @beat-twin/commands
-> @beat-twin/core
-> @beat-twin/audio-tone 浏览器试听
-> localStorage JSON 保存/加载
```
当前的 Bitwig 桥仍然存在于 `index.js`；适配器提取故意留待后续兼容性关注。浏览器试听是本地 Web Audio 预览，而不是 Bitwig 突变或 MCP 写入。
浏览器保存/加载也是本地 Playground 状态，而不是 Bitwig 突变。
浏览器模式工具是本地文档编辑，用于复制、量化处理和转调。
浏览器撤销/重做仅恢复本地 Playground 命令快照。
浏览器键盘快捷键仅调用现有的本地 Playground 操作。
浏览器时间线反馈源自本地歌曲状态，不调用 Bitwig。
浏览器命令调色板操作重用相同的本地 Playground 操作边界。
浏览器命令草图仅分析已知的本地短语；它们不是 AI 聊天路径。
## 要求
- Node.js 20 或更新版本
- pnpm 11.10.0 或更新版本
- Bitwig Studio，用于实时/手动验证
## 安装
```bash
pnpm install
```
## 运行
```bash
node index.js
```
配置您的 MCP 客户端以运行此命令从此存储库。一个便携示例存在于 [`llm-mcp/mcp.example.json`](llm-mcp/mcp.example.json) 中。
Codex 示例：
```bash
codex mcp add beat-twin --env BITWIG_HOST=127.0.0.1 --env BITWIG_PORT=8888 -- node /absolute/path/to/beat-twin/index.js
```
## 安装 Bitwig 控制器
将控制器脚本复制到您的 Bitwig 控制器脚本目录中。
Linux 示例：
```bash
mkdir -p "$HOME/Bitwig Studio/Controller Scripts/BeatTwin"
cp bitwig-controller/BeatTwin/BeatTwin.control.js "$HOME/Bitwig Studio/Controller Scripts/BeatTwin/BeatTwin.control.js"
```
macOS 用户通常使用：
```text
$HOME/Documents/Bitwig Studio/Controller Scripts/
```
Windows 用户可以将 `bitwig-controller/BeatTwin` 复制到：
```text
%USERPROFILE%\Documents\Bitwig Studio\Controller Scripts\
```
然后打开 Bitwig Studio 并手动添加控制器：
```text
Beat Twin -> Beat Twin
```
如果在安装文件之前 Bitwig 已经打开，请在测试桥之前重启 Bitwig 或重新加载控制器设置。参见 [`docs/LOCAL_MCP_SETUP.md`](docs/LOCAL_MCP_SETUP.md) 以获取本地验证命令和故障排除。
## 安全模型
拍子双胞胎默认是只读的。在 MCP 入口点，写入工具不会被 MCP 客户端列出，如果通过 MCP 服务器调用且没有启用策略，则会被阻止。
此门控仅由 Node.js MCP 服务器强制执行。Bitwig 控制器的 TCP 桥（默认 `127.0.0.1:8888`）是无身份验证的，并执行其接收到的任何 JSON-RPC 命令。它不应用写入策略。任何能够到达该端口的东西都可以驱动 Bitwig，而不受 MCP 写入策略的限制，因此 MCP 门控在 DAW 本身并不是一个障碍。作为此本地概念验证的已知限制，请将桥视为仅限受信任的本地使用：防火墙端口，不要在不受信任的网络上公开。
要启用窄写入类：
```bash
BITWIG_MCP_WRITE_POLICY=transport node index.js
```
要启用多个写入类：
```bash
BITWIG_MCP_WRITE_POLICY=transport,mixer_write node index.js
```
要为一次性测试会话启用所有写入类：
```bash
BITWIG_MCP_ENABLE_WRITES=1 node index.js
```
仅在一次性 Bitwig 项目或真实作品副本中使用写入模式。
## 测试
运行离线检查：
```bash
pnpm test
```
运行语法检查：
```bash
node --check index.js
```
实时测试需要 Bitwig Studio、控制器脚本和显式写入权限。它们与默认测试套件故意分开。
## 有用的文档
- [`docs/BT-101-SESSION-INSPECTOR.md`](docs/BT-101-SESSION-INSPECTOR.md)
- [`docs/BT-102-PROTOCOL-SMOKE.md`](docs/BT-102-PROTOCOL-SMOKE.md)
- [`docs/BT-103-POLICY-GATE.md`](docs/BT-103-POLICY-GATE.md)
- [`docs/BT-104-ARRANGEMENT-PLAN.md`](docs/BT-104-ARRANGEMENT-PLAN.md)
- [`docs/BITWIG_MANUAL_SMOKE_CHECKLIST.md`](docs/BITWIG_MANUAL_SMOKE_CHECKLIST.md)
- [`docs/FUTURE-DIRECTION.md`](docs/FUTURE-DIRECTION.md)
- [`docs/PLAYGROUND_ARCHITECTURE.md`](docs/PLAYGROUND_ARCHITECTURE.md)
- [`docs/SPRINT-2-BROWSER-AUDITION.md`](docs/SPRINT-2-BROWSER-AUDITION.md)
- [`docs/SPRINT-3-NOTE-EDITOR.md`](docs/SPRINT-3-NOTE-EDITOR.md)
- [`docs/SPRINT-4-SAVE-LOAD.md`](docs/SPRINT-4-SAVE-LOAD.md)
- [`docs/SPRINT-5-PATTERN-TOOLS.md`](docs/SPRINT-5-PATTERN-TOOLS.md)
- [`docs/SPRINT-6-UNDO-REDO.md`](docs/SPRINT-6-UNDO-REDO.md)
- [`docs/SPRINT-7-KEYBOARD-SHORTCUTS.md`](docs/SPRINT-7-KEYBOARD-SHORTCUTS.md)
- [`docs/AGENT_SETUP.md`](docs/AGENT_SETUP.md)
- [`docs/LOCAL_MCP_SETUP.md`](docs/LOCAL_MCP_SETUP.md)
## 状态
拍子双胞胎是一个实验性的本地集成，而不是一个成熟的生产工具。它作为一个开源基础发布，用于安全、可检查的 DAW 控制实验。
## 许可证
MIT
