用途:在保留无关按钮和可恢复备份的前提下,安全修改用户正在使用的 Stream Deck 配置。先确认设备、页面、按钮坐标与按压行为,只有检查当前页面后才能推断坐标。
主要能力:定位配置文件根目录(macOS 上从 ~/Library/Application Support/com.elgato.StreamDeck/ProfilesV3 开始),检查 bundle 与页面 manifest,把每次按压转换为明确动作,生成 144×144 图标与短标签,为切换状态设置不同的颜色或符号,并验证 JSON、保留未改坐标、图像尺寸、V3 Multi Action 通道和插件描述符。
使用方式:通过脚本发现与检查配置,先写声明式 spec 并用 --dry-run 预览,再以 --restart-app 应用;辅助脚本会在原子替换 manifest 前复制整个 .sdProfile bundle。可用动作包括 type、submit_text、hotkey、url、open、sequence、toggle_sequence。为保留焦点的听写场景,可用 create_background_protocol_app.py 构建后台应用包装器。
适用场景:修改 Stream Deck 页面与按钮、修复显示 ⚠️ 或运行期无效的按键、配置终端或编码代理提示词输入、无焦点切换的听写按钮。
限制与安全规则:每次写入前必须备份完整 bundle,无法备份则停止;保留请求范围外的所有坐标;按钮按压视为真实用户输入,不得在用户活跃应用中测试 Enter、删除、发送、发布、支付或破坏性快捷键;不要泄露凭据、账号、设备序列号、配置文件 UUID、日志和实时 manifest;仅在内置动作无法表达时才添加自定义插件;Modifier-only 组合和 Apple Fn 修饰键不可靠;不要将仅含修饰键的快捷键或按住说话的绑定用于切换;Stream Deck 7.4 对 V3 配置中的旧版 V2 Routine 数据会在执行时拒绝按键,7.5 中通过 Open 动作选择 .command 文件也不可靠,应改用已编译的 .app 包装器。