dsh-synthv-bridge

Synthesizer V 调音桥接 —— 把开源 synthv-agent-bridge （Apache-2.0）的 MCP 运行时接入 DeepSeek Harness，通过 Synthesizer V Studio 官方公开脚本 API 检查与编辑当前打开的工程。仅官方接口，无任何破解内容。

上游项目与我们的改动

本插件基于 synthv-agent-bridge（作者 Pengjie Zhou，Apache-2.0，v0.3.1 / 协议 v3）， 其架构：Agent（MCP 宿主）→ Node MCP 服务器 → 文件 IPC → SV 内常驻 Lua 脚本 → 官方脚本 API。 六工具语义、Guard/指纹写保护、Undo 边界、紧凑投影等全部来自上游。

我们在其之上做了两层工作：

① SV1 兼容层（vendor/bridge/synthv/ 内，SV2 行为不变）

② DSH 插件封装（本仓库其余部分，BSD-3-Clause）：vendor 打包、MCP 自动注册、 「SV 调音模式」预设、synthv-bridge 技能、状态面板、一键安装工具，以及两个通用编辑工具：

• sv_tune_curve 音高线通用编辑：read（读区间点）/ set（设点）/ clear（清区间）/

shift（整体偏移）/ scale（缩放）/ level（拉平）/ ramp（生成斜坡）/ flatten 系列预设 （填平缓出/渐入）——一步完成读-算-写-验证，模型无需 describe/contextId 多步流程；

• sv_tune_attributes 音符过渡参数批量编辑：tF0Left/tF0Right/dF0Left/dF0Right/dF0Vbr

读-改-写一次完成。

能力清单、支持矩阵与合规声明见 [NOTICE.md](NOTICE.md) 及下文。

能力

• MCP 六工具：sv_status / sv_describe / sv_query / sv_command / sv_ui / sv_review

（前缀 mcp__synthv-agent-bridge__）—— 检查工程、增删改音符、写歌词、自动化曲线、调音、 选区/视口/播放控制。

• sv_tune_curve：音高线（自动化曲线）通用编辑（读/设点/清区间/偏移/缩放/拉平/斜坡/填平预设），

内部自动处理指纹与验证，一步调用。

• sv_tune_attributes：音符过渡参数（渐入/缓出时长与偏移、颤音深度）批量编辑。
• sv_bridge_status / sv_bridge_install：一键查桥接状态 / 一键装脚本到官方 SV 脚本目录。
• 「SV 调音模式」agent 预设（新建会话预设选择器可选）：persona 内建调音工作流、

责任边界与 SV1 能力限制。

• synthv-bridge 技能：详细操作手册（action 速查、错误码、唱法约定、验证流程）。
• 状态面板：侧边栏「SV 桥接」入口（连接状态灯）+ 浮层状态卡（宿主版本/工程/安装状态/

一键安装按钮）。

支持矩阵

验证环境

• 本插件仅在 DeepSeek Harness rc.6 + Synthesizer V Studio Pro（SV1.11.2 引擎）实测验证；

SV2 Pro 为协议级理论兼容（基于上游 v0.3.1 的 SV2 真机证据），尚未在本插件形态下实测。

• 本项目使用 vibe coding 辅助开发（DeepSeek-v4 Pro）。

典型应用场景（面向不熟悉歌声合成的用户）

本插件的设计目标是让不熟悉 SV 的用户也能完成调音：专业能力由 SV 引擎 + AI 分担， 用户全程只做两件低门槛动作。

用户侧（全程仅两次手动操作）

1. SV 界面里创建自动音高：新建/打开工程 → 选中音符 → 开启音高自动模式 （让引擎先生成基础音高曲线；脚本 API 无法代做这一步，必须在界面内完成）； 2. 启动桥接：脚本 → SynthV Agent Bridge → Start SynthV Agent Bridge（每次打开 SV 一次）。

之后的一切交给 AI。

AI 侧（量化微调：用户说感觉，AI 转参数）

用户在会话里用自然语言描述听感诉求，AI 翻译成量化参数并执行：

AI 每次调整后报告改了什么、建议用户试听、按反馈迭代；每次写入可 Ctrl+Z 单独撤销。

边界（诚实告知）

• 自动音高本身必须在 SV 界面里开启（SV1.4.3 脚本 API 只读不写，实测验证）；
• 换歌手/唱法受官方 API 限制（读不到当前歌手与默认唱法），需要时用户提供唱法面板截图；
• SV1 无 detune/AI Retake/Smart Pitch/混音器，对应需求用自动化曲线替代。

安装

前置要求

• DSH 环境（本插件按 DSH 插件生态惯例打包，无 postinstall 脚本）；
• Node ≥ 20.10（桥接 MCP 子进程运行时；低于此版本子进程会静默启动失败）；
• 用户自备合法的 Synthesizer V Studio Pro（1.x 或 2.x；Basic 无脚本菜单，不支持）。

第 1 步：安装插件到 DSH

# 从 npm（发布后）
dsh plugin --profile web add @xklmy/dsh-synthv-bridge
# 或从本地 tgz / 源码目录
dsh plugin --profile web add ./xklmy-dsh-synthv-bridge-0.1.0.tgz
dsh plugin --profile web add <源码目录路径>

• 插件自带 bundle patch，会在装配时注册 host 插件（面板 API / 状态工具 / 预设与技能同步）。
• 重启 DSH 一次：host 插件把 MCP 条目自动写入 profile patch（预设与技能同步完成）。
• 再重启一次：MCP 六工具（sv_status 等）装配生效。

> 两段式生效是当前实现方式：MCP 子进程需要插件包的绝对路径，而 bundle patch 的 > !!js 求值环境没有 require，所以改为运行时展开路径写入 profile patch。

第 2 步：把桥接脚本装进 SV

三种方式任选（同一件事，幂等可重复执行）：

• 面板：侧边栏「SV 桥接」→「装到 SV1 Pro」/「装到 SV2 Pro」；
• 会话：让 agent 调 sv_bridge_install（target 为 sv1 或 sv2）；
• 手工：把 vendor/bridge/synthv/ 下两个 .lua 拷到目标目录（见下）。

目标目录（官方数据目录，Pro 才有 scripts 目录）：

第 3 步：在 SV 里启动常驻桥接（每次打开 SV 都要点一次，官方机制无法自动化）

脚本 → 重新检查脚本 → SynthV Agent Bridge → Start SynthV Agent Bridge

启动后无需任何弹窗确认；桥接常驻运行，面板状态灯变绿即就绪。 停止：脚本 → SynthV Agent Bridge → Stop SynthV Agent Bridge（或在 SV 中直接关闭工程）。

第 4 步：使用

新建会话选「SV 调音模式」预设，直接提调音需求；或先 sv_status 确认连接再操作。

AI 安装指南

> 本插件没有 postinstall 脚本：装包阶段 pnpm 只做标准安装，其余全部由 DSH 重启后的 > 装配逻辑自动完成。请按下面的时序执行并逐步验证，不要跳步。

安装时序与逐步验证

1. 装包 ``bash dsh plugin --profile web add @xklmy/dsh-synthv-bridge ` （本地 tgz / 源码目录同样适用：dsh plugin --profile web add <tgz 或目录路径>） 2. 第一次重启 DSH，然后验证 host 插件已装配： `bash curl -s http://127.0.0.1:<WEB_PORT>/@xklmy/dsh-synthv-bridge/api ` （<WEB_PORT> 为 DSH Web 端口，默认 3080） - 返回含 "bridge":{...} 的 JSON → host 插件正常（面板 API、状态工具、预设与技能同步完成）； - 404 / 无响应 → 检查 profile 的 package.json 的 bundles 是否含 @xklmy/dsh-synthv-bridge；若在，看 DSH 启动日志里该 entry 的报错。 同时确认 MCP 条目已被 host 插件写入 profile patch： `bash grep -n "mcp-synthv-agent-bridge" ~/.dsh/profiles/web/cordis.patch.yml ` 有输出 → 正常（这就是"要重启两次"的原因：MCP 条目是重启时由 host 插件展开路径写入的）。 3. 第二次重启 DSH，验证 MCP 六工具已装配： ``bash

dsh --profile web --dump-config 2>&1 | grep -c "mcp-synthv-agent-bridge"

`` 返回 ≥1 → 装配就绪。新会话里让模型自检：工具列表应含 sv_status/sv_describe/ sv_query/sv_command/sv_ui/sv_review（前缀 mcp__synthv-agent-bridge__）。 4. 装桥接脚本到 SV（幂等，可重复）： - 会话里调 sv_bridge_install（target: sv1 或 sv2）；或 - 面板「装到 SV1 Pro / SV2 Pro」按钮；或 - 手工拷贝 vendor/bridge/synthv/ 下两个 .lua 到 %USERPROFILE%\Documents\Dreamtonics\Synthesizer V Studio\scripts\SynthV Agent Bridge\ （SV1）或 ...\Synthesizer V Studio 2\scripts\SynthV Agent Bridge\（SV2）。 5. 用户在 SV 里手动启动常驻桥接（官方机制无法自动化，请明确告知用户这一步）： ` 脚本 → 重新检查脚本 → SynthV Agent Bridge → Start SynthV Agent Bridge ` 6. 连通验证：sv_status 返回 connected: true` 即可开始调音。

常见失败与应对（遇到时先对照这里，不要乱试）

卸载

dsh plugin --profile web remove @xklmy/dsh-synthv-bridge

卸载后需手动清理：从 ~/.dsh/profiles/web/cordis.patch.yml 删除 id: mcp-synthv-agent-bridge 条目（插件自身无法在卸载后清理）， ~/.dsh/.agent-presets/sv-tuning 与 ~/.dsh/skills/synthv-bridge 可留可删。 SV 端：删除官方脚本目录下的 SynthV Agent Bridge 文件夹即可。

主要事项

1. Pro 专属：脚本 API 是 SV Studio Pro 特性；Basic 免费版无脚本菜单，不支持。 2. 启动是手动的一步：官方无脚本自动运行入口，每次打开 SV 需手动 Start 一次（上游在 SV2 上同样如此）。 3. SV1 能力降级：detune / AI Retake / Smart Pitch / 轨道混音器 / 计算音素接口不可用， 对应操作返回 UNSUPPORTED_HOST_CAPABILITY，请用自动化曲线等替代（详见技能文档）。 4. 唱法（Vocal Mode）约定：官方 API 读不到歌手身份与默认唱法；涉及唱法的操作前 需提供唱法面板截图或完整唱法名称。 5. 索引 1 基；每次写入对应一个 SV 撤销记录（Ctrl+Z 可回退）。 6. 卸载注意：插件卸载后，它自动写入 profile patch 的 MCP 条目不会自动移除； 若不再使用，请手动从 ~/.dsh/profiles/<name>/cordis.patch.yml 删除 id: mcp-synthv-agent-bridge 条目，避免残留条目导致装配报错。 7. 合规：仅使用官方公开脚本 API，不解析工程文件，无破解内容（见 NOTICE.md）。 8. 安全模型（上游继承设计）：桥接通过本机临时目录下的文件 IPC与 SV 内 Lua 通信， 无网络端口、无鉴权——信任边界是"同一台机器的同一用户"。同机其他进程理论上可伪造 请求文件驱动 SV 编辑。请勿在多人共享主机 / 不受信任的同机软件环境下使用； 可用 SYNTHV_AGENT_BRIDGE_DIR 把 IPC 目录改到用户私有位置（两侧自动一致）。 9. 可选环境变量： - SYNTHV_AGENT_BRIDGE_DIR：自定义 IPC 目录（插件、MCP、Lua 三侧一致读取）； - SYNTHV_SCRIPTS_DIR_SV1 / SYNTHV_SCRIPTS_DIR_SV2：覆盖 SV 脚本目录检测 （Documents 被 OneDrive 重定向 / 非默认数据目录时使用）； - SYNTHV_DOCUMENTS_DIR：覆盖「我的文档」根目录检测。

开发

npm run sync:vendor   # 从上游仓库同步 vendor 运行时（需上游先 npm run build）
npm run build         # 构建 host + client（build.sh 内含 vendor 同步）

上游仓库：synthv-agent-bridge 的本地 clone（含 SV1 兼容修改与补丁脚本， 改动清单见其 docs/SV1-adaptation-changes.md）。仓库位置任意， 用 SYNTHV_BRIDGE_UPSTREAM 环境变量指定，构建时由 scripts/sync-vendor.mjs 读取。

致谢

架构灵感来自 Haruki Okada 的概念验证项目 ocadaruma/mcp-svstudio—— 它首次演示了「本地 MCP 服务器 + SV 内常驻 Lua 脚本」经文件通信的可行路线； 上游 synthv-agent-bridge 在此之上重实现了请求关联、校验、过期上下文保护、 撤销记录、跨平台路径与更完整的工具面，本插件进一步完成 SV1 兼容与 DSH 生态封装。

Synthesizer V 与 Synthesizer V Studio 是 Dreamtonics 的产品与商标。 本独立项目与 Dreamtonics 无关联，亦未获得其背书。

许可

• 本插件：BSD-3-Clause
• vendor/bridge：Apache-2.0（synthv-agent-bridge 上游 + SV1 兼容性修改）