内容
# 光谱打击中心 - 企业级统一游戏与环境同步控制平台
> **一款面向未来的、类玻璃形态的智能照明中心，用于统一控制 WLED、WiZ、OpenRGB 和 Windows 动态照明设备，实现实时屏幕同步。**
## 📸 界面预览
<div align="center">
<img src="frontend/public/dashboard_preview.png" alt="光谱打击中心仪表盘" width="90%" style="border-radius: 12px; margin-bottom: 20px; border: 1px solid rgba(255,255,255,0.08);" />
<p><i>图 1: 统一的类玻璃形态仪表盘概览</i></p>
<br />
<img src="frontend/public/music_sync_preview.png" alt="音乐同步引擎" width="90%" style="border-radius: 12px; margin-bottom: 20px; border: 1px solid rgba(255,255,255,0.08);" />
<p><i>图 2: 实时 8 波段 FFT 音乐同步仪表盘，带有色板编辑器</i></p>
<br />
<img src="frontend/public/screen_sync_preview.png" alt="环境屏幕同步" width="90%" style="border-radius: 12px; margin-bottom: 20px; border: 1px solid rgba(255,255,255,0.08);" />
<p><i>图 3: 交互式显示坐标区域映射和枪火特效触发设置</i></p>
</div>
---
光谱打击中心是一款统一的、高性能的、低延迟的智能照明控制中心和同步服务。它聚合了多种本地物联网协议，包括 **WLED 控制器（HTTP/UDP）**、**飞利浦 WiZ 灯泡（UDP JSON-RPC）**、**OpenRGB SDK 服务器（TCP）** 和 **Windows 动态照明（UWP WinRT LampArray）**，成为一个单一的、响应迅速的控制平台，优化用于沉浸式游戏环境。
专为实时应用而设计，光谱打击中心包括一个 **SignalRGB 风格的像素绘制网格**，用于精细的灯条控制，一个 **交互式屏幕环境同步（Ambilight）映射画布**，支持 HTML5 拖放赋值，**多区域 LED 分段同步**，**真实色彩手动通道校准**，以及一个完全兼容的 **模型上下文协议（MCP）服务器**，用于 AI 代理编排。
---
## 📋 目录
- [快速入门](#快速入门)
- [功能](#功能)
- [系统架构](#系统架构--数据流)
- [技术深入](#技术深入)
- [API 参考](#api-端点参考)
- [项目结构](#项目目录结构)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [安全](#安全)
- [许可证](#许可证)
---
## 快速入门
### 前置条件
- **Python 3.9+** （Windows/macOS/Linux）
- **Node.js 18+** 和 **npm 9+**
- **Git**
- 智能照明设备：WLED、WiZ、OpenRGB 或 Windows 动态照明
### 安装和运行（5 分钟）
**1. 克隆和设置后端：**
```bash
git clone https://github.com/AyushSharma297/SpectraStrike-Hub.git
cd SpectraStrike-Hub/backend
pip install -r requirements.txt
python main.py
```
后端运行在 `http://localhost:8000` （带有自动文档的 FastAPI）
**2. 设置前端（新终端）：**
```bash
cd frontend
npm install
npm run dev
```
前端运行在 `http://localhost:5173`
**3. 开始使用：**
- 打开浏览器访问 `http://localhost:5173`
- 点击 **"扫描设备"** 以自动发现本地照明控制器
- 从仪表盘控制亮度、颜色、特效和屏幕同步
### 演示功能
一旦运行，尝试这些：
- **色彩调色板生成器**：使用 6 种和谐模式创建和谐的 5 色方案
- **场景**：立即捕获和恢复设备状态
- **分组**：组织设备并一起控制它们
- **计划**：设置每日自动化规则
- **实时统计**：监控设备数量、LED 总数、同步 FPS、运行时间
**GitHub 仓库**：[github.com/AyushSharma297/SpectraStrike-Hub](https://github.com/AyushSharma297/SpectraStrike-Hub)
---
## 功能
光谱打击中心包括以下生产就绪的功能：
### 核心控制
- ✅ **多协议支持**：WLED、WiZ、OpenRGB、Windows 动态照明
- ✅ **设备自动发现**：快速本地子网扫描和验证
- ✅ **实时控制**：即时电源、亮度、颜色和特效更改
- ✅ **分组管理**：创建设备组并控制它们
- ✅ **场景和预设**：捕获和应用设备状态快照
### 高级同步和环境
- ✅ **屏幕环境同步（Ambilight）**：从屏幕捕获实时边缘/区域颜色映射
- ✅ **多区域分段**：将灯条分成独立的屏幕区域
- ✅ **交互式画布映射**：拖放坐标区域赋值
- ✅ **双线性降采样**：硬件优化的颜色平均
- ✅ **音乐同步引擎**：高保真实时环回音频可视化器，带有 8 种响应模式（节拍脉冲、声吧、频谱分割器、能量 VU、色彩器官、低音闪烁、单脉冲、频谱波）和自定义渐变色板自定义
### 颜色和校准
- ✅ **真实色彩手动校准**：3x3 矩阵校正硬件颜色色调
- ✅ **颜色选择器和预设**：快速访问常用颜色
- ✅ **调色板生成器**：6 种色彩和谐方案（互补色、三色组等）
- ✅ **实时绘画笔刷**：像素级 LED 控制，网络节流 75ms
### 自动化和集成
- ✅ **计划和自动化**：每日规则，带有星期几 + 时间 + 操作目标
- ✅ **模型上下文协议（MCP）**：AI 就绪集成（Claude、Gemini、Cursor）
- ✅ **FastAPI REST API**：完整的端点覆盖，自动生成文档
### UI/UX
- ✅ **类玻璃形态设计**：现代磨砂玻璃美学和动画
- ✅ **实时仪表盘**：实时统计（设备数量、LED、同步 FPS、运行时间）
- ✅ **响应式布局**：适用于桌面和移动设备
---
## 系统架构和数据流
光谱打击中心在反应式 SPA 前端、多线程 FastAPI 协调器和低延迟网络适配器之间分离关注点。
### 系统拓扑图
```mermaid
graph TD
%% 前端层
subgraph 前端 [React 单页应用]
UI[类玻璃形态仪表盘]
PaintGrid[LED 绘画笔刷画布]
LayoutCanvas[坐标区域映射器]
SegmentMgr[多区域分段管理器]
Calibrator[真实色彩通道校准器]
end
%% API 网关和控制
subgraph 后端 [FastAPI 后端 Web 服务器]
API[ASGI API 端点]
SyncEngine[屏幕同步守护线程]
DeviceRegistry[内存设备注册表]
end
%% 硬件协议
subgraph 协议 [硬件适配器]
WLED[WLED 客户端 HTTP / UDP 21324]
WiZ[WiZ UDP 客户端 UDP 38899]
OpenRGB[OpenRGB SDK 客户端 TCP 6742]
WDL[Windows 动态照明 WinRT]
end
%% 硬件节点
subgraph 硬件 [物理灯节点]
Strip[WLED 灯条]
Bulb[WiZ 智能灯泡]
PC1[OpenRGB 风扇/内存控制器]
PC2[UWP HID LampArray 外设]
end
%% 映射
UI -->|HTTP POST 控制 / 绘画| API
LayoutCanvas -->|HTTP POST 布局映射| API
SegmentMgr -->|HTTP POST 分段映射| API
Calibrator -->|HTTP POST 校准| API
PaintGrid -->|限流 UDP 绘画流| API
API -->|获取状态 / 注册表| DeviceRegistry
API -->|初始化同步| SyncEngine
SyncEngine -->|捕获监视器帧| Screen[OS 显示 API via MSS]
Screen -->|双线性降采样| SyncEngine
SyncEngine -->|实时颜色流| 协议
API -->|直接 API 控制| 协议
WLED -->|DRGB 数据包| Strip
WiZ -->|JSON-RPC 广播| Bulb
OpenRGB -->|SDK 数据包| PC1
WDL -->|COM / WinRT 调用| PC2
```
---
## 2. 技术深入
### 2.1 屏幕捕获环境同步的工作原理
实时环境照明同步循环在专用后台工作线程（`screen_sync.py` 中的 `ScreenSyncWorker`）中执行，以防止阻塞主 FastAPI Web 线程。
```text
+------------------+ +-----------------------+ +--------------------+ +-------------------+
| 屏幕捕获 | | 坐标裁剪 | | 降采样 | | 网络流 |
| （MSS API） | --> | （左/顶部/右侧等） | --> | （双线性 1x1/32x32）| --> | （DRGB UDP / WDL） |
+------------------+ +-----------------------+ +--------------------+ +-------------------+
```
#### 步骤 1：高性能屏幕捕获
传统的屏幕捕获方法（例如 PIL `ImageGrab`）会带来大量的 CPU 开销和延迟。光谱打击中心使用 **`mss`（多屏幕截图）** 库。在 Windows 上，`mss` 直接与操作系统显示驱动程序使用 **桌面复制 API（DXGI）** 接口。这直接从 GPU 内存中获取显示缓冲区，以原始像素格式获取，绕过操作系统窗口合成瓶颈。
#### 步骤 2：图像转换
原始像素缓冲区以 `BGRA` 布局捕获。我们使用以下方法在内存中实例化 Pillow `Image` 对象：
```python
img = Image.frombytes("RGB", sct_img.size, sct_img.bgra, "raw", "BGRX")
```
这是一个零复制内存操作，在不到 2 毫秒的时间内剥离 alpha 通道并将 BGR 转换为 RGB 结构。
#### 步骤 3：坐标区域裁剪和分段
为了支持多区域环境照明，根据用户的坐标映射裁剪屏幕：
* **左侧区域**：裁剪帧的左侧 15% 宽度：`img.crop((0, 0, int(w * 0.15), h))`
* **右侧区域**：裁剪帧的右侧 15% 宽度：`img.crop((int(w * 0.85), 0, w, h))`
* **顶部区域**：裁剪帧的顶部 15% 高度：`img.crop((0, 0, w, int(h * 0.15)))`
* **底部区域**：裁剪帧的底部 15% 高度：`img.crop((0, int(h * 0.85), w, h))`
* **中心区域**：裁剪中央 50% 框：`img.crop((int(w * 0.25), int(h * 0.25), int(w * 0.75), int(h * 0.75)))`
#### 步骤 4：双线性降采样
计算数百万个像素的平均颜色是 CPU 密集型且低效的。相反，光谱打击中心使用双线性降采样：
1. 为了获得一个区域的单个平均颜色（例如，对于 WiZ 灯泡、OpenRGB 或 Windows 动态照明），我们将裁剪的区域缩减为 **1x1 像素**：
```python
img_tiny = cropped.resize((1, 1), Image.Resampling.BILINEAR)
r, g, b = img_tiny.getpixel((0, 0))
```
双线性插值自动在硬件速度下计算整个图像的加权平均颜色。
2. 对于 WLED Ambilight 边框数组，我们将裁剪的边框区域降采样到 **32x32 网格**，然后沿着相应的路径跟踪采样颜色以获取每个单独的 LED 索引。
#### 步骤 5：WLED 多区域分段映射
当启用多区域 LED 分段同步时，单个 WLED 控制器的灯条分成索引级分段（例如，LED 0 到 15 映射到左侧区域，LED 15 到 30 映射到顶部区域）。
* 在线程运行时，同步工作器初始化一个表示 `led_count * 3` 的黑色字节数组。
* 对于每个分段，工作器裁剪相应的屏幕区域，平均或采样颜色，并仅在指定的索引范围内叠加它们（`start` 到 `end`）。
* 统一的有效载荷合并并在一个 UDP 数据包有效载体中调度，保留网络带宽并降低驱动器侧的开销。
#### 步骤 6：通过网络协议流式传输
一旦计算出颜色，它们会立即通过低开销的 UDP 套接字或直接 WinRT COM API 发送到其各自的硬件驱动程序。
---
### 2.2 真实色彩手动通道校准
较便宜的 LED、物理扩散和灯泡外壳通常会引入颜色色调（例如，纯红色看起来略带橙色，因为绿色渗透，或纯白色看起来太暖/黄色）。光谱打击中心通过实施 **真实色彩手动通道校准** 系统，使用 3x3 线性矩阵变换来解决这个问题：
1. **用户输入校准**：用户命令设备输出纯红色 `[255, 0, 0]`、纯绿色 `[0, 255, 0]` 和纯蓝色 `[0, 0, 255]`。他们检查光输出并选择他们实际感知的颜色（看到的颜色）。
2. **矩阵公式化**：感知的颜色形成 3x3 颜色失真矩阵 $M$ 的列：
$$M = \begin{bmatrix} R_{seen\_red}/255 & G_{seen\_red}/255 & B_{seen\_red}/255 \\ R_{seen\_green}/255 & G_{seen\_green}/255 & B_{seen\_green}/255 \\ R_{seen\_blue}/255 & G_{seen\_blue}/255 & B_{seen\_blue}/255 \end{bmatrix}$$
3. **逆矩阵计算**：后端 FastAPI 服务器计算矩阵逆 $M^{-1}$。如果 $M$ 是奇异或不稳定，则回落到单位矩阵。
4. **实时校正**：所有输出颜色 $C = [R, G, B]^T$（无论是静态颜色滑块、WLED 实时绘画笔刷或实时屏幕捕获同步帧）都乘以逆矩阵后传输：
$$C_{calibrated} = \text{clip}_{0}^{255}(M^{-1} \times C)$$
这中和了硬件特定的通道串扰和颜色偏移，确保高保真环境照明。
---
### 2.3 设备接口协议
#### WLED JSON API 和 UDP 实时流
WLED 设备通过两个不同的接口进行控制，取决于操作：
1. **控制命令（HTTP）**：设置亮度、电源状态和动画使用 HTTP POST 请求到 `http://<ip>/json/state` 携带 JSON 有效载体：
```json
{
"on": true,
"bri": 128,
"seg": [{"fx": 9, "sx": 128, "ix": 128] }
}
2. **实时实时流（UDP）**：发送像素帧的高速度使用 **DRGB 实时协议** 在 UDP 端口 `21324`。该避免 HTTP 连接协商开销。 二进制数据包结构是定义为：
* **字节 0**：协议类型（值：`2` 表示 DRGB）。
* **字节 1**：超时秒数，WLED 默认返回其以前的纯色或动画（值：`2`）。
* **字节 2+**：每个 LED 的连续 RGB 值： `[R0, G0, B0, R0, R1, B1, ...]`
#### 飞利浦 WiZ UDP JSON-RPC
飞利浦 WiZ 灯泡通过 **UDP 端口 `38899`** 进行本地通信，使用基于 JSON-RPC 的协议。这是无状态的，不需要持久的 TCP 握手：
1. **设置灯泡颜色/电源**：
* 目标地址：`UDP <bulb_ip>:38899`
* 有效载体：
```json
{"method": "setPilot", "params": {"state": true, "r": 255, "g": 0, "b": 128}}
```
2. **查询状态**：
* 有效载体：
```json
{"method": "getPilot", "params": {}}
```
* 灯泡返回当前电源状态、调光百分比和 RGB/开尔文温度。
#### OpenRGB SDK 协议
OpenRGB 设备（主板、内存模块、显卡、外设）通过连接到本地 **OpenRGB 服务器的 TCP `6742`端口** 来控制。`openrgb-python` SDK 封装了二进制 TCP 协议，允许光谱打击中心直接向特定硬件区域发送颜色数据包。
#### Windows 动态照明（UWP WinRT）
在 Windows 11 上，HID 兼容的照明设备（键盘、主板、鼠标阵列）由操作系统原生管理。光谱打击中心通过加载 Windows 运行时（WinRT）元数据库 (`winsdk`) 来控制这些：
1. **设备发现**：
我们使用以下命令查询系统以获取实现 HID LampArray 接口的设备：
```python
selector = LampArray.get_device_selector()
devices = await DeviceInformation.find_all_async(selector)
```
2. **颜色更新**：
对于每个连接的 `LampArray`，我们使用以下命令应用 RGB 颜色，并按客户端的亮度进行缩放：
```python
c = Color()
c.r, c.g, c.b, c.a = r, g, b, 255
lamp_array.set_all_colors(c)
```
*注意：确保在 Windows 设置 -> 个性化 -> 动态照明中启用“背景光控制”，以便在应用程序窗口最小化时允许控制。*
### 2.4 音乐同步引擎和 FFT 分析的工作原理
实时音频可视化在一个单独的守护进程线程（`music_sync.py` 中的 `MusicSyncWorker`）中处理，以高速处理立体声音频帧，而不会阻塞主应用程序。
```text
+------------------+ +------------------+ +-----------------------+ +--------------------+
| 音频回路 | | FFT 分析 | | 自动增益控制| | 响应模式 |
| （声卡） | --> | （scipy.fftpack）| --> | （AGC 峰值衰减） | --> | （DRGB UDP 流） |
+------------------+ +------------------+ +-----------------------+ +--------------------+
```
#### 步骤 1：低延迟音频回路捕获
使用 `soundcard` 库，光谱打击中心在环回模式下直接钩入操作系统音频子系统（Windows 上的 WASAPI）。它以 44.1 kHz 的采样率捕获 512 个样本的音频块：
- **零延迟驱动程序热插拔：** 如果插入耳机或更改默认系统播放设备，捕获循环会自动重新初始化并钩住新的活动默认驱动程序。
#### 步骤 2：快速傅里叶变换（FFT）
为了将音频映射到光频率，捕获的立体声信号合并为单声道，并使用快速傅里叶变换（FFT）处理：
```python
fft_data = np.abs(np.fft.rfft(chunk_data))
```
原始 FFT 频率然后分组到 8 个对数频带中，代表标准频率组（次低音、低音、低中频、中频、高中频、存在感、亮度、特雷布尔），使用自定义缩放矩阵。
#### 步骤 3：自动增益控制（AGC）和包络滤波
为了在所有音量级别上保持光输出的响应：
1. **动态归一化：** 系统实时跟踪峰值音频能量，并以缓慢衰减参数 ($0.997$) 进行跟踪。原始信号除以此跟踪峰值，以将幅度归一化到 $0.0$ 和 $1.0$ 之间。
2. **包络滤波器：** 应用平滑的上升/下降攻击和衰减包络（attack=0.65，decay=0.60），以防止闪烁，确保光瞬变的立即响应。
#### 第 4 步：轻度渲染与调度
归一化的振幅值被输入到所选的响应模式中：
- **VU 表**: 灯光根据整体能量逐步填充灯带。
- **声霸**: 8 个频段中的每一个都映射到 WLED 灯带的一个独立部分，像图形均衡器一样发光。
- **节拍脉冲**: 灯光在瞬态低频（低音）能量触发时闪烁为实心基准色。
- **频谱波**: 一个滚动的渐变波，其滚动速度由整体节拍能量调制。
---
## 3. 网络子网扫描优化
子网扫描检查本地子网中所有 IP 地址以查找响应式照明控制器。为了快速完成此操作而不阻塞服务器：
1. **IP 子网识别**: 我们查询主机上的活动 IP 配置，使用 RFC 1918 私有子网检查 (`192.168.0.0/16`, `10.0.0.0/8`, `172.16.0.0/12`) 过滤掉 VPN 接口（例如 Radmin 或 Hamachi），并提取本地 `/24` 子网前缀。
2. **异步端口扫描**: 使用 Python 的 `asyncio.open_connection`，我们触发 254 个同时进行的端口 80（WLED）检查，并并发发送 WiZ UDP 搜索查询。
3. **超时阈值**: 连接超时时间上限为 **0.4 秒**。由于扫描是完全异步的，因此扫描一个完整的 `/24` 类 C 子网只需不到 1 秒。
4. **验证握手**: 如果端口 80 打开，扫描器会发出快速 HTTP GET 请求到 `/json/info`。只有返回有效 WLED 模式的设备才会被注册。
5. **WiZ 广播扫描**: 使用直接 UDP 广播到 `255.255.255.255` 和本地广播边界（例如 `192.168.1.255`），然后进行高速单播扫描，以绕过路由器级客户端隔离。
---
## 4. UI 性能与客户端限制
在 React 界面中使用 **LED 画笔** 网格进行绘图时，点击和拖动会以高频率（通常每秒 100+ 次）触发鼠标移动事件。
为每个像素变化发送 HTTP 或 UDP 数据包将使浏览器网络队列饱和并淹没后端。
为了解决这个问题，SpectraStrike Hub 使用 **客户端流限制**：
1. 绘图时，颜色变化立即保存到本地 React 状态数组 (`ledColors`) 中，以保持视觉绘图网格高度响应（60+ FPS）。
2. React 应用程序中运行一个后台轮询计时器，固定间隔为 **75ms**（约 **14 FPS**）：
```javascript
useEffect(() => {
const streamInterval = setInterval(() => {
if (paintDirtyRef.current && selectedDeviceId) {
streamPaintColors(selectedDeviceId, ledColorsRef.current);
paintDirtyRef.current = false;
}
}, 75);
return () => clearInterval(streamInterval);
}, [selectedDeviceId]);
```
3. 如果在 75ms 窗口内修改了网格（`paintDirtyRef.current == true`），则发送一个包含整个灯带像素配置的批量有效载荷到后端。这样可以在低网络负载的同时平衡 UI 响应性。
---
## 5. 模型上下文协议（MCP）集成设置
SpectraStrike Hub 通过基于 stdio 的模型上下文协议服务器公开其功能，允许 LLM 接口查询、检查和控制本地灯光。
### 5.1 Claude 桌面集成
1. 在 Windows 上找到您的 Claude 桌面配置文件：
`%APPDATA%\Claude\claude_desktop_config.json`
2. 在 `mcpServers` 下配置 `spectrastrike-hub` 条目：
```json
{
"mcpServers": {
"spectrastrike-hub": {
"command": "python",
"args": [
"C:/Users/aayus/.gemini/antigravity-ide/scratch/wled-wiz-hub/backend/mcp_server.py"
]
}
}
}
```
3. 重启 Claude 桌面。现在您可以命令 Claude 与您的灯光交互。
### 5.2 Gemini / Antigravity 设置
对于基于 Gemini 的代理，请使用以下属性注册 MCP 服务器：
* **服务器 ID**: `spectrastrike-hub`
* **传输**: `stdio`
* **命令**: `python`
* **参数**: `["C:/Users/aayus/.gemini/antigravity-ide/scratch/wled-wiz-hub/backend/mcp_server.py"]`
### 5.3 通用 MCP 客户端（Cursor，Zed）
* **Cursor**: 在 `设置` -> `功能` -> `MCP` 中添加一个 `command` 类型服务器：
```bash
python C:/Users/aayus/.gemini/antigravity-ide/scratch/wled-wiz-hub/backend/mcp_server.py
```
* **Zed 编辑器**: 在 `settings.json` 中：
```json
"context_servers": {
"spectrastrike-hub": {
"command": "python",
"args": ["C:/Users/aayus/.gemini/antigravity-ide/scratch/wled-wiz-hub/backend/mcp_server.py"]
}
}
```
---
## 6. API 端点参考
后端 FastAPI 网络服务器在端口 **8000** 上运行，并公开以下 REST 接口：
### 6.1 `GET /api/devices`
检索所有活动注册控制器的列表及其缓存的运行时配置。
### 6.2 `POST /api/scan`
触发对活动本地子网的异步扫描。返回新注册的物理硬件节点的列表。
### 6.3 `POST /api/devices/add`
强制在特定 IP 地址注册一个设备（适用于离线设备）。
### 6.4 `POST /api/devices/{device_id}/control`
对设备应用立即更改（电源、亮度、纯色和预设）。
### 6.5 `POST /api/devices/{device_id}/paint`
接收 WLED 灯带上单个 LED 的实时颜色网格，并通过 UDP 流式传输。
### 6.6 `POST /api/devices/{device_id}/calibration`
应用手动颜色校准矩阵值用于特定的照明节点。
* **请求模式**:
```json
{
"r_seen": [255, 10, 0],
"g_seen": [0, 255, 5],
"b_seen": [0, 15, 255]
}
```
### 6.7 `GET /api/devices/{device_id}/calibration`
检索为设备保存的感知校准颜色值。
### 6.8 `POST /api/sync/layout`
保存到设备的屏幕坐标区域分配。
### 6.9 `POST /api/sync/segments`
保存 WLED 灯带的索引级屏幕坐标区域分配。
### 6.10 `GET /api/sync/segments`
检索所有已注册的分段映射。
### 6.11 `POST /api/sync/screen`
控制屏幕环境同步线程工作器。
---
## 7. 项目目录结构
仓库遵循干净的 monorepo 结构，将 Python ASGI 后端与 Vite React SPA 前端分离：
```text
wled-wiz-hub/
├── .gitignore # 根级 Git 忽略配置
├── LICENSE # Apache 2.0 许可证
├── README.md # 本文档
├── CONTRIBUTING.md # 贡献指南和开发设置
├── SECURITY.md # 安全策略和漏洞披露
├── CODE_OF_CONDUCT.md # 社区标准和行为期望
├── run.bat # Windows 协调器启动实用程序脚本
├── backend/ # FastAPI 应用程序后端
│ ├── main.py # FastAPI 应用程序、路由器、设备缓存设置
│ ├── mcp_server.py # 模型上下文协议（MCP）服务器端点
│ ├── scanner.py # 多播 SSDP 设备查找器（UDP 和 TCP 端口）
│ ├── screen_sync.py # 后台捕获线程和缓冲区处理器
│ ├── wled.py # WLED 客户端包装器（HTTP JSON 和 UDP DRGB）
│ ├── wiz.py # WiZ 客户端包装器（原始套接字 UDP JSON-RPC）
│ ├── pc_lights.py # OpenRGB TCP SDK 连接库
│ ├── windows_dynamic_lighting.py # Windows 动态照明客户端（WinRT 集成）
│ └── requirements.txt # Python 后端模块列表
└── frontend/ # Vite React 仪表板应用程序
├── package.json # Node 配置和脚本运行器
├── vite.config.js # Vite 构建配置
├── eslint.config.js # 代码样式验证规则
├── index.html # Web 入口点索引文件
├── public/ # 静态矢量和图标
└── src/ # 前端代码库
├── main.jsx # 应用程序组件安装程序
├── App.jsx # 仪表板 SPA 客户端 UI 代码（2700+ 行）
├── index.css # 核心游戏玻璃形态设计系统（1000+ 行）
└── assets/ # 组件图标
```
---
## 故障排除
### 后端无法启动
- **错误**: `ModuleNotFoundError: No module named 'fastapi'`
- **解决方案**: 在 `backend/` 文件夹中运行 `pip install -r requirements.txt`
- **错误**: `Port 8000 already in use`
- **解决方案**: 在 `main.py` 中更改端口或杀死使用端口 8000 的进程
### 设备在扫描中未出现
- **检查**: 设备必须位于同一本地网络（WiFi/以太网）
- **检查**: 防火墙可能阻塞 UDP 端口 38899（WiZ）或 21324（WLED）
- **尝试**: 通过 `POST /api/devices/add` 手动添加设备，附带设备 IP
### 屏幕同步不工作
- **Windows**: 确保在设置 → 个性化 → 动态照明中启用“后台光控制”
- **MSS 库**: 确保安装了 `mss` 库：`pip install mss`
- **检查**: 验证设备支持屏幕同步（WLED、OpenRGB 支持此功能；WiZ 灯泡使用颜色平均）
### 前端构建警告
- **解决方案**: 运行 `npm run build` 以识别问题。构建应以零错误/警告完成
### 颜色不匹配预期
- **解决方案**: 使用 **TrueColor 手动校准**：
1. 将设备设置为纯红色 [255,0,0]、绿色 [0,255,0]、蓝色 [0,0,255]
2. 记录视觉上感知的颜色
3. 使用校准端点纠正颜色矩阵
---
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取：
- 开发设置说明
- 代码样式指南
- 拉取请求流程
- 功能开发检查清单
**快速 PR 检查清单：**
- [ ] 复刻仓库
- [ ] 创建功能分支：`git checkout -b feature/your-feature`
- [ ] 进行更改并本地测试
- [ ] 验证：`npm run build`（零警告）和后端正确启动
- [ ] 使用约定消息提交：`feat: your feature description`
- [ ] 推送并打开拉取请求
---
## 安全
要报告安全漏洞，请参阅 [SECURITY.md](SECURITY.md)。
**不要** 为安全问题创建公共问题。相反：
- 通过电子邮件联系维护人员，提供漏洞详细信息
- 在公开披露之前允许一段时间进行修复
- 遵循 90 天的责任披露窗口
---
## 许可证
SpectraStrike Hub 在 **Apache License 2.0** 下发布。
您可以：
- ✅ 将此软件用于任何目的（商业或个人）
- ✅ 修改和分发代码
- ✅ 将其包含在您的项目中
您必须：
- 📋 包括原始许可证和版权声明
- 📋 公开您所做的任何修改
- ⚠️ 在分发时提供 Apache 2.0 许可证的副本
参见 [LICENSE](LICENSE) 以获取完整条款。
**版权 © 2026 SpectraStrike Hub Contributors**
---
## 技术合规性说明
### WiZ 套接字集成
SpectraStrike Hub 中的 WiZ 灯控引擎（[backend/wiz.py](backend/wiz.py)）使用通过 UDP 端口 38899 通信的低级套接字，使用开放的本地 JSON-RPC 协议。
- **零专有 SDK**：仅使用内置 Python 套接字
- **无逆向工程**：使用公开记录的 JSON-RPC 方法（`getPilot`、`setPilot`）
- **完全合法**：无加密密钥、专有二进制文件或固件块存储
### 堆栈
- **后端**: Python 3.9+，FastAPI，Uvicorn
- **前端**: React 19，Vite，Lucide 图标，自定义玻璃形态 CSS
- **样式**: 1000+ 行现代玻璃形态动画
- **协议**: WLED（HTTP/UDP），WiZ（UDP JSON-RPC），OpenRGB（TCP），Windows 动态照明（WinRT）
---
## 支持与问题
- 📖 **文档**: 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发指南
- 🐛 **错误报告**: [打开问题](https://github.com/AyushSharma297/SpectraStrike-Hub/issues) 并提供重现步骤
- 💡 **功能请求**: [打开问题](https://github.com/AyushSharma297/SpectraStrike-Hub/issues) 描述用例
- 💬 **讨论**: [GitHub Discussions](https://github.com/AyushSharma297/SpectraStrike-Hub/discussions) 用于一般问题
- 📧 **电子邮件**: ayushsh762@gmail.com
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器