内容
# qsys-tools
> 开源工具，用于 **QSC Q-SYS** 音频/视频系统 — 从您的 shell、代码或 AI 代理控制 Core，并在 Mac 上原生运行 Q-SYS Designer。
[](https://www.npmjs.com/package/qsys-cli)
[](https://www.npmjs.com/package/qsys-qrc)
[](https://www.npmjs.com/package/qsys-mcp)
[](https://www.npmjs.com/package/qsys-mac)
[](https://nodejs.org)
[](#licensing)
每个 Q-SYS Core 和 Q-SYS Designer 的 **模拟模式** 都提供 QSC 的公开 **QRC** 协议（JSON-RPC 2.0 over TCP，端口 1710）。这与 Crestron/AMX 集成使用的外部控制接口相同。这些工具原生支持该协议：**无需 QSC 代码，无需 SDK，无需硬件即可开发**。
| 软件包 | 描述 |
|---|---|
| [`qsys-cli`](packages/qsys) | CLI（命令：`qsys`）— 状态、组件库存、获取/设置控件，带有斜坡、实时监视、快照 |
| [`qsys-qrc`](packages/qsys-qrc) | TypeScript QRC 客户端 — 线框、变更组、保持活动、透明自动重新连接、类型化协议表面 |
| [`qsys-mcp`](packages/qsys-mcp) | [MCP](https://modelcontextprotocol.io) 服务器（MCP 注册表中的 `io.github.reowens/qsys-mcp`）— 18 个工具，允许 AI 代理检查和驱动实时 Q-SYS 系统 |
| [`qsys-mac`](packages/qsys-mac) | npm 启动器（命令：`qsys-mac`）— 下载/验证签名的 Q-SYS Mac 安装程序 DMG 并委托其助手 |
| [`qsys-mac-installer`](packages/qsys-mac-installer) | **Q-SYS Designer for macOS** — 签名/公证的 BYO 安装程序包装应用 + DMG 源 |
## 快速入门 — shell
```sh
export QSYS_HOST=192.168.1.10 # 您的 Core，或 127.0.0.1 用于 Designer 模拟
npx qsys-cli status # 引擎/设计状态
npx qsys-cli ls # 列出组件
npx qsys-cli get MainGain # 读取命名控件
npx qsys-cli set MainGain -6 --ramp 2
npx qsys-cli watch MainGain # 流式传输更改直到 Ctrl-C
npx qsys-cli snapshot load Bank 1 --ramp 1
```
```
$ qsys status
设计 RobertOwens-L1（代码 Hd4b6C9TXKzL）
平台 模拟器（模拟器）
状态 活动
$ qsys set-component Main_Mixer input.1.gain -6 --ramp 2
名称 值 字符串 位置
input.1.gain -6 -6.00dB 0.585
```
使用 `npm i -g qsys-cli` 全球安装命令（二进制文件为纯 `qsys`）。每个命令都接受 `--json` 用于脚本编写；`watch` 发出 JSON 行。
## 快速入门 — AI 代理（MCP）
```sh
claude mcp add qsys -- npx -y qsys-mcp
```
或在任何 MCP 客户端配置中：
```json
{
"mcpServers": {
"qsys": { "command": "npx", "args": ["-y", "qsys-mcp"] }
}
}
```
然后要求代理连接到您的 Core（或 Designer 模拟器），它可以读取仪表、翻转静音、斜坡增益、监视控件的更改并召回快照 — 在 Core 重启时自动重新连接。详情请参见 [`packages/qsys-mcp`](packages/qsys-mcp)。
注册表感知的 MCP 客户端可以将其发现为 `io.github.reowens/qsys-mcp`。
## 快速入门 — 您自己的代码
```sh
npm install qsys-qrc
```
```ts
import { QrcClient } from 'qsys-qrc';
const qrc = new QrcClient({ host: '192.168.1.10' });
await qrc.connect();
const status = await qrc.statusGet(); // 类型化助手…
await qrc.setControl('MainGain', -6, 2); // 值 -6，2 秒斜坡
const [gain] = await qrc.getControl(['MainGain']);
await qrc.send('Component.GetComponents'); // …或原始 QRC 方法
qrc.close();
```
变更组（基于轮询的监视）、组件访问、快照和登录都由类型化助手覆盖 — 请参见 [`packages/qsys-qrc`](packages/qsys-qrc)。
## Mac 上的 Q-SYS Designer
对于大多数用户，请使用签名的 DMG 安装程序应用。运行它一次以创建 `Q-SYS Designer.app`，然后删除安装程序应用或将其保留为启动、重新安装和删除的小型管理器。已安装的 Designer 应用及其应用程序支持数据与安装程序应用保持独立。
直接 DMG 路径：
```sh
open https://github.com/reowens/qsys-tools/releases/tag/qsys-mac-installer-v0.1.4
```
或使用 npm 启动器：
```sh
npx qsys-mac install "/path/to/Q-SYS Designer Installer 10.4.0.exe"
```
它下载并验证签名的 Q-SYS Mac 安装程序 DMG，安装它并运行捆绑的助手。npm 包不包含 Q-SYS Designer 或应用程序负载。您提供**您自己的**免费 Designer 安装程序下载（BYO — 不重新分发 QSC 的任何内容）。
对于只读支持诊断，运行：
```sh
npx qsys-mac doctor
```
当前 macOS 先决条件：Rosetta 2。签名的 DMG 捆绑了 Wine、.NET、`7z`、图标工具、`msiinfo` 和本机助手二进制文件；正常设置不需要 Homebrew 或主机 Python。
更喜欢 GUI 安装程序应用？Homebrew 可以安装它：
```sh
brew tap reowens/qsys
brew trust reowens/qsys
brew install --cask qsys-mac-installer
open -a "Q-SYS Mac Installer"
```
`brew trust` 是当前 Homebrew 对第三方 Cask Taps 的要求。
签名的安装程序源位于 [`packages/qsys-mac-installer`](packages/qsys-mac-installer)。它将 Wine + .NET 部署到应用程序支持并为您提供真正的 Dock/Finder/菜单栏公民。当前的签名的 DMG 是 [`qsys-mac-installer 0.1.4`](https://github.com/reowens/qsys-tools/releases/tag/qsys-mac-installer-v0.1.4)。
奖励：Designer's **模拟模式** 在 `127.0.0.1:1710` 上提供 QRC，因此上述所有工具都无需硬件即可与其配合使用 — 这就是此存储库的工具被验证的方式。
## 没有硬件？
将任何工具指向 Q-SYS Designer 运行在模拟模式（`--host 127.0.0.1`）。两个值得了解的协议事实：QRC 没有方法来 *枚举* 命名的控件或快照库（您需要从设计中获取它们的名字），并且 `Component.GetComponents` 仅返回具有启用脚本访问的组件。
## 开发
这是一个 [pnpm](https://pnpm.io) 工作区（Node 22.13+；pnpm 来自 `packageManager` 字段 via [corepack](https://nodejs.org/api/corepack.html)）。
```sh
git clone https://github.com/reowens/qsys-tools.git
cd qsys-tools
corepack enable # 提供固定的 pnpm
pnpm install
pnpm -r build # 按依赖顺序构建软件包（qsys-qrc 首先）
pnpm run typecheck
pnpm test
```
e2e 套件（QRC 集成、MCP-over-mock 端到端和透明-重新连接/AutoPoll-replay 回归测试）针对 [`qsys-mock-core`](packages/qsys-mock-core) 运行 — 一个存储库中的、设计驱动的 Q-SYS Core 模拟器 — 因此 `pnpm test` 在没有硬件的情况下练习完整的协议。更深入的一致性测试（验证-对抗-Designer 渲染、斜坡/仪表和真实 Q-SYS 设计库）使用单独的、更完整的模拟器。
`qsys-mac-installer` 单独使用 Xcode 构建 — 请参见 [`packages/qsys-mac-installer`](packages/qsys-mac-installer) (`scripts/package.sh` 用于签名/公证管道)。
维护者发布步骤在 [`RELEASE.md`](RELEASE.md) 中记录。
在从此源代码检出工作时，请使用工作区脚本而不是 `npx qsys-mac`，以免将本地工作区软件包与已发布的软件包混淆：
```sh
pnpm run qsys-mac -- status
pnpm run qsys-mac -- install "/path/to/Q-SYS Designer Installer 10.4.0.exe"
```
## Licensing
原始的 `qsys-tools` 源代码是 **MIT** 许可的，包括 QRC 软件包、`qsys-mac` npm 启动器和 `qsys-mac-installer` 包装应用。
签名的 macOS 安装程序 DMG 是多许可证二进制分发，因为它捆绑了可重新分发的第三方组件，例如 Wine、.NET、p7zip、icoutils、`msiinfo` 及其运行时库。这些组件仍然在其自己的许可证和通知下 — 请参见 [`packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md`](packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md)。
每个软件包都有自己的 LICENSE 文件。
## 免责声明
这是一个独立的开源项目，**与 QSC, LLC 无关、未得到 QSC, LLC 的认可或赞助**。“Q-SYS”和“Q-SYS Designer”是 QSC, LLC 的商标，仅用于命名。这些工具使用公开记录的 QRC 协议，不包含任何 QSC 代码。
