内容
# Decky 插件工作室
用于 **Decky 加载器** 插件开发的 VS Code / Cursor 扩展：实时 IDE 预览，MCP 工具用于在真正的 Steam Deck 上构建/部署/调试，复合截图和屏幕录制，以及用于您的插件仓库的代理包。
> **实时预览仍处于测试阶段。** 它非常适合快速 UI 和 RPC 迭代，但对焦、布局、Steam 输入和 gamescope 合成仍需要设备端质量保证。参见 [预览限制](docs/PREVIEW_LIMITATIONS.md)。
## 您将获得
| 功能 | 说明 |
|---------|----------------|
| **实时预览** | QAM 大小 WebView，支持 HMR，虚拟游戏手柄，硬件模拟器，用于真实 `main.py` RPC 的 Python 边车 |
| **MCP 工具** | 用于 `deck.deploy`、`deck.captureScreenshot`、`deck.record`、预览套件、隧道/摄取的代理和命令 |
| **复合捕获** | 包括 QAM + 您的插件 UI 的截图和录像（非原始游戏仅 kmsgrab） |
| **初始化包** | 将 `AGENTS.md`、Cursor/VS Code MCP 配置、技能和可选 `scripts/` 放入您的插件仓库 |
| **创建新插件** | 克隆 decky-plugin-template，重命名样板，运行 Init Pack |
## 安装
1. 从 [GitHub Releases](https://github.com/decky-plugin-studio/decky-plugin-studio/releases) 下载最新的 `.vsix` 文件
2. **扩展** → **…** → **从 VSIX 安装…**
3. 重载编辑器
状态栏（右下角）显示已安装的版本、预览/隧道状态和摄取计数。
## 快速入门
### 1. 打开插件工作区
任何包含 `plugin.json` 和 `main.py` 的文件夹。此仓库包含 [example-plugin/](example-plugin/) 用于烟雾测试。
### 2. 配置您的 Deck（远程开发）
使用 MCP **`deck.configure`** 或在您的插件仓库中创建 `.env`：
```env
DECK_IP=192.168.x.x
DECK_USER=deck
```
使用 MCP 配置时，Deck 凭证也存储在 `~/.config/decky-plugin-studio/deck.env` 中。
### 3. 初始化包
命令面板 → **`Decky: Init Pack`**
复制代理指导、MCP 配置、技能和可选脚本（`record-deck`、`screenshot-deck`、预览套件）。
### 4. 打开预览（测试阶段）
命令面板 → **`Decky: Open Preview`**
- 编辑 `src/` → Vite HMR 在 QAM 帧中
- 编辑 `main.py` → Python 边车重新启动并保留状态
**请勿仅基于预览发布** - 部署到 Deck 进行对焦和布局错误的质量保证。
### 5. 日常循环
```
预览（快速 UI）→ 插件构建 → deck.deploy → 设备端质量保证
```
| 任务 | 操作 |
|------|-----|
| 构建插件 zip | MCP `plugin.build` 或您的 `pnpm run build` |
| 部署到 Deck | MCP `deck.deploy` 或 **Decky: Deploy to Deck** |
| 截图（QAM + 插件） | MCP `deck.captureScreenshot` - 先打开 QAM + 插件 |
| 屏幕录制 | MCP `deck.record` - 在捕获前/中打开 QAM + 插件 |
| Deck 调试日志 | `deck.startTunnel` → `deck.probeIngest` / `deck.tailIngest` |
| 代理自动化 | 参见 [MCP 工具](docs/MCP_TOOLS.md) |
**工件** 位于您的插件工作区：`screenshots/`、`recordings/`。
### 6. Cursor / VS Code 中的 MCP
初始化包后，您的插件仓库的 `mcp.json` 指向扩展的 MCP 服务器。工具在 [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) 中有文档记录。
示例代理流程：
- `deck.configure` → `plugin.build` → `deck.deploy` → `deck.captureScreenshot`
- `preview.start` → `preview.runSequence` 进行烟雾测试
- `deck.record`，参数为 `{ seconds: 15, mode: "game", quality: "compressed" }`
## 捕获前提条件
对于 **游戏模式** 截图和录像：
1. 部署您的插件 (`deck.deploy`)
2. 在 Deck 上打开 **QAM**
3. 打开 **您的插件面板** 并在捕获期间保持可见
录像使用复合的 pipewire-gamescope（游戏）或 wf-recorder（桌面）。如果仅游戏平面捕获成功，它们会 **关闭** - 除非您传递 `allowNonPluginUi: true`。
可选：`deck.installCaptureHelper` 将 `studio-record` / `studio-capture` 安装到 Deck 上的 `~/.local/bin`。
## 开发此扩展
- **分支模型：** 功能开发在 `develop` 上 → 合并到 `main` 并在 `extension/package.json` 中进行版本更新 → CI 发布 GitHub Release + VSIX
- 本地构建：[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
## 更多文档
- [MCP 工具参考](docs/MCP_TOOLS.md)
- [预览限制](docs/PREVIEW_LIMITATIONS.md) - 测试预览 vs 设备端质量保证
- [消费者同步（bonsAI 及其他插件）](docs/MCP_CONSUMER_SYNC.md)
- [设备质量保证运行手册](docs/device-qa-runbook.md)
## 许可证
Apache-2.0 - 参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
