SynthV 对话工作台

面向 Synthesizer V Studio 2 Pro 独立版 / Windows 的本地调教助手，以 2.2.1 为开发与宿主验证基准。通过官方 Lua 脚本读取工程和选区、调整少量参数，再采集软件输出，用 A/B 试听、信号指标和可选音频模型评审检查结果。本项目为独立开发的实验性工具，与 Dreamtonics 没有官方关联；不包含 SynthV 软件、声库或示例歌曲。

本版提供 Flutter 原生 Windows 工作台：三栏布局、可拖动侧栏、黑白浅色/深色主题、独立会话与设置页面，保留当前 Python 调教核心、Lua 桥接和 stdio MCP。桌面应用自行启动受控本机后台，不需要打开浏览器。会话、音频素材、录音、回收站、平台设置和组合曲线预览均已有原生页面；默认只读，模型服务默认停用。旧网页暂保留兼容入口。

桌面版 0.2.0 统一了紧凑工具栏与属性面板，新增“连接管理”用于诊断脚本目录错配、连接已有桥接或备份安装匹配脚本，并完善窗口退出、后台收尾和播放器释放。脚本运行后仍显示未连接时，先打开连接管理查看真实心跳与目录；无需先开启工程写入权限。

**桌面使用入口：**完整 Windows 发行目录中双击 synthv_desktop.exe；必须保留旁边的 DLL、data 静态资源及 backend。源码开发在准备好 Python 与 Flutter 环境后执行 ./scripts/start-desktop.ps1，沿用本仓库业务数据。发行包默认使用 %LOCALAPPDATA%\SynthV Assistant\data，不会自动搬移旧资料。完整使用与迁移说明见 桌面工作台，开发与打包见 desktop/README.md。

桌面和旧网页切换前，应先结束任务并关闭原服务，避免两个客户端同时管理同一数据目录。界面迁移没有改变“生成预览 → 用户确认 → 应用”的边界。本轮桌面验证使用隔离数据、模拟模型和虚构会话，不代表已完成真实云端听评或真实工程写入验收。

可以只发送文字，也可以显式附带当前选区或音频。纯文字咨询与参数规划可使用支持所选协议的文字模型；附带音频时才要求模型支持音频输入。 模型先提出建议，实际参数预览由 SynthV 桥接生成，单项或组合应用都须由用户确认。对话流程使用模拟模型和隔离模拟宿主验证，真实云模型尚未验证。历史真机验证覆盖短选区的气声单项预览、应用、恢复及按进程录音；本轮另外在真实宿主与正式网页验证了已有偏移下的原生音高、颤音包络、此前失败的气声及张力的四参数组合预览，完整选区与所有原参数指纹未改变；尚未执行真机整批应用。不代表所有复杂曲线均可处理，也不代表模型已经听过或改善了歌声。

当前能做什么

调教规划默认保留已有演唱，通过不同音符的局部小幅包络修饰；新桥接向模型提供当前参数采样，避免只依据默认值盲目叠加。原生音高重绘仍作为明确的替换操作。实现思路、参考项目及测试边界见 调教生成逻辑与参考记录。

选中音符之间有空隙时，参数会影响从第一个选中音符开始到最后一个选中音符结束的整个连续区间。本版不是逐字智能调教器，也不自动识别应修改哪个音素。共享于多个位置的音符组会拒绝写入。

本版不开放轨道/音符组克隆、和声生成或通用事务；不调用未知原生接口，不直接改写 .svp 工程文件。官方脚本 API 的稳定性仍依赖 SynthV 版本和声库，精简桥接并不等于已修复宿主原生缺陷。

Related MCP server: Ableton Copilot

环境要求

以下为源码及旧网页的环境要求。完整桌面发行包已带 Python/.NET 后台；Flutter Windows 前端仍需要系统具备 Microsoft Visual C++ x64 运行库。具体安装与数据迁移见 桌面说明。

• Python 3.10 或更高版本，项目依赖安装在本目录 .venv。

• Windows build 20348 或以上；Windows 11 满足这一最低版本条件。常见 Windows 10 build 19045 不满足本版按进程回录要求。

• Synthesizer V Studio 2 Pro 独立版及可用声库；此原型面向 2.2.1 开发，其他版本需重新验收。

• 按进程采集器为 x64 .NET 10 程序：源码构建需要 .NET SDK 10；运行已构建文件需要相应 .NET 10 x64 运行时。SDK 包含运行时。

• 本机浏览器。控制台只监听 127.0.0.1，默认端口 8765。

源码安装需要在自己的机器上构建采集器，并确认运行时、声卡驱动和音频输出路径可用。已完成的短片段回录验证不涵盖所有 ASIO 设置、声卡或工程。MP3 导入另外需要自行安装 FFmpeg 并加入 PATH；仅使用 PCM WAV 时不需要 FFmpeg。

页面、外观与素材管理

左侧导航在中间切换会话、音频素材、录音、回收站和设置，原会话的未发送草稿会保留。设置和素材选择使用主页面，无需在弹窗中操作。离开模型设置页会清空尚未保存的密钥输入；保存中的配置会先完成当前请求。

在设置页选择“跟随系统”“浅色”或“深色”。默认跟随系统，并随系统外观即时更新。主题选择与两侧栏宽度只保存在当前浏览器；拖动边栏分隔线可改变宽度，也可聚焦分隔线后用方向键调整，双击可恢复默认宽度。窄窗口改用可展开的侧栏，避免把中央页面挤出屏幕。

会话与素材可设置名称、星标和备注。备注用于本地整理，不会自动加入 AI 请求。删除时可选择“移到回收站”或“永久删除”，回收站也支持逐项永久删除。移入回收站可恢复；永久删除需在页面内确认，随后移除本机对应会话文件或音频及索引，不能恢复。删除会话不会连带删除音频，也不会撤销已经应用到 SynthV 的参数或删除工程、备份。历史消息保留已删除附件的名称，但不能继续播放该音频。

音频素材页的底部操作栏与列表滚动区域分开，便于确认已选附件。请求过程中显示阶段、等待时间和实际接收进度；这些信息不表示模型已经完成响应或参数已经写入。

消息中的音频与正文放在同一气泡，默认显示文件名、时长和“试听”。点击后才展开播放器，用户主动播放前不预加载；收起会暂停。长文件名可悬停查看，已删除素材保留名称和状态，不继续播放。

“录音”页控制 SynthV 播放并采集其输出，不开启麦克风。页面内的“读取选区”会直接读取 SynthV 当前选区并填入起点与时长，无需先到右侧读取。读取失败或没有选区时清空旧范围，避免误录上一次片段；也可以手动填写范围。选区不足 1 秒时按最少 1 秒填写，超过 30 秒时只填前 30 秒并显示提示。填写名称后开始录音，完成后可试听、到素材库管理或附到会话；附到会话还不等于发送给模型。现有右侧 A/B 录制与比较仍可使用。

首次准备

使用 Git 时，先在准备存放项目的目录打开 PowerShell；也可以下载仓库压缩包并进入解压目录。

# 获取源码并进入项目目录；已经下载源码时跳过这两行。
git clone https://github.com/blockshy/synthv-assistant.git
Set-Location -LiteralPath .\synthv-assistant

以下命令在含 pyproject.toml 的项目根目录执行，只在项目 .venv 安装 Python 依赖，不安装全局依赖；需要网络下载依赖。本项目按源码目录运行，网页、Lua 与原生采集器源码应保留在同一目录树内。

# 仅在尚无 .venv 时创建；本机默认 Python 应满足 3.10+ 要求。
py -3 -m venv .venv

# 使用项目解释器安装本地包及声明的依赖，不需要激活虚拟环境。
.\.venv\Scripts\python.exe -m pip install -e .

# 首次安装或更新采集器源码后执行；需要本机已有 .NET SDK 10。
.\.venv\Scripts\python.exe -m synthv_assistant build-capture

# 打包 Lua，并安装到 SynthV 2 的脚本目录；已有同名脚本会先备份。
.\scripts\install-bridge.ps1

安装目录为：

%APPDATA%\Dreamtonics\Synthesizer V Studio 2\scripts\SynthVAssistant.lua

安装脚本不会打开 SynthV，不会修改用户工程，也不会修改任何 AI 客户端的全局配置。可先运行 scripts/install-bridge.ps1 -WhatIf 查看目标路径。

随后在 SynthV 中执行以下操作：

1. 手动打开一个测试工程，先另存一份 .svp 副本。

2. 在“脚本 / Scripts”菜单重新扫描脚本；若未出现，可重启 SynthV。

3. 运行 SynthV Assistant。同一工程会话只运行一个桥接实例。

4. 在钢琴卷帘中选中一小段音符，等待软件完成合成，并停止播放。

项目路径或 SYNTHV_ASSISTANT_DATA 改变后，需要重新运行安装脚本。Lua 打包文件包含本机 IPC 目录，不能直接拿另一台机器生成的 Lua 文件使用。

启动工作台

# 在当前 PowerShell 中启动本地服务；Ctrl+C 停止服务。
.\scripts\start.ps1

# 端口被占用时，可以显式选择其他本地端口。
.\scripts\start.ps1 -Port 8766

建议使用 Chrome 打开 本地工作台。启动脚本只使用已经准备好的 .venv，不会自动安装依赖、启动 SynthV 或读取 .env。

Chrome 已用于界面和音频播放验证。部分内嵌浏览器曾出现音频播放崩溃，兼容性尚未确认；遇到该问题时，请用独立 Chrome 窗口打开同一地址。

第一次使用对话工作台，可按以下顺序操作：

1. 在左侧“模型设置”编辑默认平台，或“新建平台”保存名称、服务协议、默认模型和密钥；需要时将已配置平台设为新会话默认。回到会话后，在输入区选择平台、模型和推理强度；模型留空使用平台默认值。纯文字任务可选择文字模型，需要发送音频时选择支持音频输入的模型。

2. 点击“新会话”，输入调教要求，每条最多 4000 字符。一般咨询可取消“附带当前选区”，无需连接 SynthV；需要可执行调教提案时，在 SynthV 选中音符并保留该选项。勾选后若桥接未连接或没有选区，服务会明确拒绝，不会悄悄省略选区。

3. 如需听音，打开“音频素材”上传片段或选择已有录音，再把所需文件附加到本次消息。不附音频也能发送文字；历史消息中的音频不会自动再次发送。

4. 发送后可查看等待时间与实际回复进度；如果供应商返回可见思考摘要，也会显示。正式解释和提案要等完整回复通过校验后才出现。单项建议直接预览；多项建议点击“生成组合预览”，一次查看音符、各参数曲线和失败原因，再确认应用列明的成功项。生成新预览后，旧预览的确认资格失效。

5. 需要写入时，从右侧“工程工具”开启“允许修改选区”。后端会先自动备份磁盘上的已保存工程；尚未保存为可访问 .svp 的工程会被拒绝。助手不会替你开启写入。应用后可试听或录制 B，也可继续讨论下一步。

已有建议可通过两个入口继续使用，无需重复发送要求：

• 原目标重新预览：桥接重启后，原工程、音符组、音符内容及时间、声线设置一致时，未应用建议点击预览即可基于当前参数生成新预览，参数手动编辑后也无需重新请求模型。音符仅重编号或返回顺序变化不会使建议失效；旧预览编号和确认资格不会沿用。

• 复用到当前选区：先在 SynthV 选择目标音符，再点击原建议的此按钮。工作台在本地追加一份新提案，并自动请求只读预览；不调用模型、不重新发送音频，保留原建议和应用记录，同时使旧预览确认资格失效。用户可以选择另一个片段、音符组或工程，也可以在参数已编辑后基于当前值重新预览。确认前需核对新范围、曲线及成功项。

复用的通用参数增量以当前参数为基线，曲线按新选区时长缩放。原生音高及音高偏移曲线还要求音符数量、含组移调的实际音高与归一化秒起止位置一致，允许整段平移或等比拉伸；仅音高相同而相对节奏不同不足以复用音高曲线。当前宿主不支持或结构不匹配的项会列明原因并排除，其他可用参数仍可预览；全部不适用时不创建新提案。跨片段复用不等于已经验证演唱效果，本功能尚未进行真实工程的跨片段写入验收。

已经确认应用成功的提案，在 SynthV 撤销或工作台恢复后，可使用“撤销后重新预览”或“重新生成组合预览”。服务确认原目标与完整原参数状态后，生成新预览，再由你确认应用；桥接重连也须通过完整指纹检查。已应用方案不能通过复用再次叠加到原目标的重叠范围。尚未撤销、继续编辑或缺少可靠指纹时不能直接重用已应用动作；显示“结果未知”的方案也不能通过复制解锁，应先在 SynthV 检查实际状态或撤销，再重新规划。所有入口仍遵循最多 128 个音符、30 秒、连续选区范围及共享音符组拒绝写入的限制。

右侧手动工具仍可独立完成 A/B 流程：

1. 检查“调教桥接”状态，点击“读取工程”和“读取选区”。

2. 指定片段起点与时长，先“录制 A”，并确认能听到目标声音。

3. 开启“允许修改选区”。服务会先自动备份磁盘上的已保存工程，备份成功后才请求宿主开启写入。这份备份不包含尚未保存的编辑，重要工程仍建议先在 SynthV 保存或另存工作副本。

4. 选择一个参数，小幅调整并预览。核对音符数量、时间范围和调整量，再应用。

5. 保持相同起点、时长和工程混音设置，录制 B；试听并比较指标。

6. 需要恢复时，回到上次修改的音符组，使用“恢复最后修改”；如曲线已被手动改动或在 SynthV 中撤销，助手会拒绝覆盖。

“恢复最后修改”保留当前桥接会话最近一次修改的恢复快照；组合应用失败且自动回滚未完成时，也会保存待恢复记录，不是完整工程版本管理。最近一次若为组合应用，一次恢复会核对并还原整批参数；SynthV 原生撤销中也只建立一条整批撤销记录。重启桥接会丢失该内存快照。参数写入不会自动保存 .svp，最终结果由你在 SynthV 中确认和保存。

需要 Airy、Chest 等声线模式、分段音高或组合预览时，请先更新并重新运行 Lua 桥接，再读取选区。组合流程要求宿主返回 capabilities.batchPreview=true，旧脚本不会自动降级为连续逐项操作。右栏可切换均匀增量与曲线编辑，支持画布和键盘数值点输入；聊天提案也可使用同一目录和曲线契约。原生音高曲线使用绝对 MIDI 音高，音高偏移使用音分增量，两者不能混用。 选区已有非零音高偏移时，原生曲线仍可预览，旧偏移原样保留。图中显示原生控制曲线，不代表最终合成基频；不会清除旧偏移或偷偷转换旧提案。跨界曲线、选区内引导点和无法验证的边界继续按真实原因拒绝。详细单位、限制、点数含义和接口见 声线参数与曲线编辑。

录音实际包含什么

采集器使用 Windows WASAPI 进程树回录，目标为 SynthV 进程及其子进程。它不打开麦克风，也不会在进程回录失败后自动改录整个系统。

录到的是 SynthV 当前完整混音，包括未静音的伴奏和其他轨道。需要单独评审人声时，请在录制 A 之前自行设置静音或独奏，并在 A/B 之间保持一致；工作台不会擅自改变轨道混音。

WAV 格式为 44100 Hz、双声道、PCM16。每段文件比指定播放时长多约 1 秒准备/尾部余量。播放控制与音频采集之间存在小量延迟，本版不保证样本级起点同步，不应用于毫秒级音素对齐。A/B 不做自动对齐、响度归一化或重采样。

如果 SynthV 使用 ASIO 等绕过受支持 Windows 路径的输出方式，回录可能为空或失败。先确认录音，再考虑使用能被该接口捕获的输出模式；不要把空录音当作“没有调教差异”。RMS 不是 LUFS，变响也不等于更自然或更好听。

多个 SynthV 实例同时运行时，需在启动助手前通过 SYNTHV_ASSISTANT_PID 指定目标进程号，并确保正在运行桥接的工程属于该进程；第一版建议只打开一个实例。

模型平台、会话选择与音频附件

左侧 “模型设置” 可管理最多 20 个平台，含原有“默认平台”。默认平台继续使用原来的加密配置，旧版 A/B 听评与 MCP review_recordings 仍使用它；会话可另外选择命名平台。新建或切换会话平台不会改写默认平台，也不会自动切换其他会话。本地工程读取、手动调参、录音、试听和指标比较不依赖模型配置。

1. 在“编辑平台”中选择已有平台，或点击“新建平台”。自定义平台需要名称；默认平台名称固定。

2. 选择 OpenAI / OpenAI 兼容服务、Google Gemini 或 通义千问 Qwen，填写平台默认模型、HTTPS Base URL、API key 和 5～180 秒等待超时。流式请求收到新的正文或思考内容后自动续期，连续无有效输出才超时，另有独立的 30 分钟总上限；其他非流式调用按 HTTP 等待超时处理。Qwen Omni 的 A/B 听评在服务端内部收集流式响应，也适用有效输出续期。切换协议会填入对应默认值，但不会自动保存。只发文字时模型无需支持音频；附带音频或使用 A/B 听评时，需使用兼容音频输入的模型。

3. 点击 “保存并立即生效”。设置在本机由当前 Windows 账户加密保存，下次启动保留，无需重启服务。仅保存设置不会调用供应商、验证密钥或上传音频。 保存后可点击 “设为新会话默认”。之后新建的会话自动使用该平台的默认模型与默认推理设置；已有会话继续使用原来的选择。此偏好不改变独立 A/B 听评的原有配置。

4. 回到会话，在输入区选择平台、模型及推理强度。这三个选择随会话保存；模型留空沿用平台默认模型，推理选“模型默认”时不额外指定强度。每次请求读取所选平台的完整配置快照，新设置从下一次请求生效。界面的“已配置”不表示“连接验证通过”。

会话输入区还可选择“绘制模式”或“控制点模式”，该偏好独立随会话保存，作用于之后的请求。绘制模式优先使用精简参数曲线；AI 原生音高方案优先逐音符描述少量音分变化，再由本机按真实音符时长和移调生成曲线。控制点模式的音高调整使用 pitchDelta 音分偏移，不会自动改成原生绝对音高。

正式预览统一分轨：上方音符按实际 MIDI 音高排列，下方参数与音符共用时间轴。单参数显示原单位；组合图将不同参数按各自显示量程归一化为 0–100%，用最多五种主题颜色区分，图例保留原量程与单位，移动指针可看原始数值。图例可隐藏单条曲线，也可显示调整前虚线；不同参数的百分比不能直接比较绝对大小。实际节点只画宿主返回的节点，不把采样点补成控制点；历史选区或时间不一致时拒绝混画。颜色仅用于这些数据曲线，工作台整体仍为黑白主题。

右侧手动音高草稿仍保留与音符叠加的编辑视图：pitchDelta 按“乐谱音高 + 音分增量 / 100”显示参考位置，数值输入和提交仍是音分。正式预览使用上述分轨布局，曲线和音符都不代表实际录音或测得基频。

模型输入框既可手动填写，也可点击旁边的刷新按钮获取所选平台的模型目录。只有显式刷新目录才会向该平台发送模型列表请求，请求会使用该平台密钥，但不附带会话、选区或音频；打开页面、切换平台、查询本地能力规则和保存设置都不会自动访问供应商。列表失败时仍可手动填写模型 ID。

成功获取的模型目录会缓存在本机，新会话、网页刷新和服务重启后继续复用。缓存按平台及其协议、API 地址和凭据区分；更换连接配置后旧目录失效，改名、修改默认模型或超时不会无谓清空目录。缓存超过 7 天会在模型框提示中标记，可继续使用；需要更新时点击刷新即可，系统不会因过期自动联网。首次升级到缓存版、尚未获取过目录或缓存不可用时，需要主动刷新一次，或直接手填模型 ID。

模型目录通常不提供完整的音频、推理或流式能力。界面的能力说明来自本地保守规则，不能保证每个兼容平台都实现了同名模型的全部参数。已知不支持的推理档位会被拒绝，明确不支持音频的模型不能提交音频附件；能力未知时需以平台实际支持为准。非默认推理强度只在用户选择后传递，失败不会自动降级、换模型或重试。

点击发送后，用户消息立即显示在对话中；服务端记录返回后替换本地待发送展示，避免重复气泡，不再等待模型完成才一起显示。失败时明确展示状态，不自动重发模型请求。聊天请求显示实际阶段、等待秒数和已收到的字符数量，不模拟完成百分比。思考摘要仅展示 API 实际返回的可见内容；没有返回时会明确说明，不代表请求没有进行，也不保证每个平台都提供摘要。摘要只供查看，不进入下一轮历史提示词，不作为可执行调教计划。流式回复完整结束并通过校验后，才生成正式模型回复和可预览提案；此处“流式”指接收模型回复，音频仍以完整附件发送。

密钥不会回显，也不会写入浏览器 localStorage 或 URL。保持同一服务协议和 API 根地址时，密码框留空可保留已保存密钥；更换协议或地址必须重新填写。取消、关闭或保存失败都会清空本次输入的密钥；保存失败保留其他字段供修正。若其他页面更新过设置，本页会拒绝覆盖，需手动“重新加载已保存设置”。

“清除密钥并停用”只清除当前编辑平台的凭据并保存停用状态，不影响其他平台；默认平台停用后也不会退回使用环境中的旧密钥。再次启用需重新配置。选择“暂不启用模型服务”再保存同样会停用该平台并清除其密钥。本地录音、试听和指标比较继续可用。

默认平台尚无网页本机配置时，仍支持读取启动进程的环境变量；新增命名平台不继承环境密钥。.env.example 仅是字段说明，程序和 PowerShell 脚本不会自动读取 .env。环境变量方式的变更需要重启对应进程；网页保存的默认平台配置优先于环境变量，立即供后续使用该平台的请求读取。

# 显式选择供应商后才启用模型请求；把占位值替换为账户可用的模型 ID。
$env:SYNTHV_AUDIO_PROVIDER = 'openai'
$env:SYNTHV_AUDIO_MODEL = 'your-model-id'

# OPENAI_API_KEY 应由当前进程环境或你的凭据管理工具提供。
# 不要把密钥写进 README、MCP 示例、源代码或可提交的配置文件。
.\scripts\start.ps1

已实现 openai、gemini 和 qwen 的文字与音频输入分支。默认模型仅是配置起点，实际可用性取决于所选服务和账户。纯文字请求不附加音频字段；OpenAI 兼容服务用于听音时，还须支持本项目的 input_audio 格式。

使用 Qwen 时，在网页选择该协议并填写对应平台的 API Key 和地址。百炼北京默认地址为 https://dashscope.aliyuncs.com/compatible-mode/v1；中文千问AI平台按量地址为 https://maas.qianwenaiapi.com/compatible-mode/v1，国际 QwenCloud 为 https://maas.qwencloudapi.com/compatible-mode/v1。也可使用百炼对应地域的业务空间专属 Base URL。请按密钥来源选择地址，项目不会将凭据自动换发到其他平台。千问AI平台官方地址、QwenCloud 官方地址

qwen3.8-flash 为默认文字模型，qwen3.8-max 同样用于文字调教：这两款官方均不支持音频输入。需要上传音频或做 A/B 听评时，请主动选择 qwen3.8-omni-flash。工作台不会自动替换型号或重试收费请求。Flash 官方能力、Max 官方能力、Omni Flash 官方能力

这三款 Qwen 提供模型默认、关闭、低、中、更高，对应省略强度字段或 none / low / medium / xhigh。模型默认不代表关闭思考。音频采用内联 Base64，Qwen Omni 还要求编码后的单段字符串小于 10 MB，因此本地素材上传成功不代表一定满足所选平台的发送上限。显式刷新百炼模型列表使用原生 /api/v1/models，结果仍按平台与凭据保存在本机缓存，普通新会话不会自动重新拉取。千问AI平台与 QwenCloud 没有官方兼容模型列表接口，请使用预设或手填型号。完整配置、地域地址、音频限制与官方依据见 模型与音频说明。

上传素材时，仅向本地工作台传输文件并进行校验/转换，不会调用模型。支持 WAV 和 MP3，单个原文件与转换后的 WAV 均不得超过 12,000,000 字节，时长须大于 0 且不超过 60 秒。WAV 使用 16/24/32 位整数 PCM；MP3 依赖本机已安装且可从 PATH 找到的 FFmpeg，程序不会自动下载安装。缺少 FFmpeg 或转换失败会明确提示，可改传 PCM WAV；超长文件整体拒绝，不会悄悄截断。

每条消息最多附带 2 个文件，实际发送的 WAV 合计不得超过 12,000,000 字节。只有发送消息时本次显式选中的附件，或显式提交的 A/B 听评录音，才会发往模型服务。历史音频不自动重发；纯文字消息只发送文字和勾选的安全选区摘要，不包含本机工程路径、进程号或完整工程。当前真实云模型尚未验证，模型建议也不会自动应用到工程。

接入支持本地 MCP 的 AI 客户端

本项目使用 stdio MCP，与浏览器工作台共用同一业务层及 Lua 桥接。客户端需要能够启动本地进程。示例见 MCP 配置示例，其中占位路径必须替换为自己的实际绝对路径。

该 JSON 是通用 mcpServers 结构，不是自动安装器；各客户端可能使用其他格式。请在客户端中添加以下进程配置，程序不会自动修改 Codex 或其他客户端的全局配置：

command: <项目绝对路径>\.venv\Scripts\python.exe
args:    -m synthv_assistant mcp

MCP 客户端与工作台应使用相同的 SYNTHV_ASSISTANT_DATA，或共同使用默认项目 data 目录。operation.lock 跨进程串行化参数变更、写入模式切换、预览和整段录音；其他入口忙时会明确拒绝新操作，不会并行修改或插入另一段录音。client.lock 另外保证单个 IPC 请求排他。

跨进程锁已经过测试，但不自动替用户安排整轮 A/B 工作流。仍建议顺序完成“录制 A → 预览并应用 → 录制 B → 比较/恢复”；遇到忙碌提示，应等待当前操作完成再读取状态，不要反复提交。同一数据目录可以被多个入口使用，后台任务仍需通过创建它的服务进程查询。

可向 AI 描述任务：“读取当前选区，先录制 A；把气声增加 0.05，给我看范围和预览，等我确认后再应用并录制 B、比较。”MCP 提供独立的预览和应用工具；是否逐次询问确认由客户端的工具审批策略负责，接入时应要求用户确认写入，不能把工具调用本身视为独立的人工确认机制。模型不能仅凭曲线数据声称已经听到声音；需要调用实际录音与听评流程。

如果客户端与主模型支持 MCP AudioContent 和音频输入，还可调用 get_recording_audio，直接取得真实 WAV。服务器能返回音频不代表每个客户端都会把它交给模型；不支持时使用 review_recordings 调用单独配置的音频模型。

常用工具按流程分为：status / get_project / get_selection；set_write_mode / preview_parameter / preview_curve / apply_preview / restore_last_edit；start_recording / get_job / list_recordings；compare_recordings / review_recordings / get_recording_audio。后台任务必须在创建它的同一服务进程中查询；服务重启后录音文件仍保留，但任务编号不再有效。

数据与验证

运行数据默认保存在项目 data 目录：

日常状态检查不需要测试依赖。首次运行完整测试前，请安装项目的 test 可选依赖，其中 lupa 用于在 Lua 5.4 虚拟机中验证桥接行为；该依赖不属于运行工作台的必需项。安装仍仅作用于项目 .venv。

# 仅读取助手状态，不更改 SynthV 工程。
.\.venv\Scripts\python.exe -m synthv_assistant status

# 首次执行完整测试前安装 test 可选依赖，包含 Lua 虚拟机测试所需的 lupa。
.\.venv\Scripts\python.exe -m pip install -e '.[test]'

# 在项目目录执行本地测试；音频模型测试使用 mock，不会产生云端调用。
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

验证范围

自动化测试覆盖 Lua 桥接、MCP stdio、跨进程锁、Windows DPAPI、会话状态机、永久删除、平台配置、本地音频分析、采集生命周期和模拟模型协议。浏览器流程使用隔离数据、合成音频和模拟宿主验收。测试命令见上方；测试数量随代码变化，以实际运行结果为准。

真实宿主验证基准为 SynthV Studio 2 Pro 2.2.1 / Windows：既有版本已在测试工程副本的短选区验证读取、气声小幅预览、应用、写后校验、恢复及非静音 A/B 回录。本次参数扩展另完成七种通用参数、宿主声线与手动补充模式、原生音高的只读预览；确认精简表示、连续音高坐标及预览前后工程参数指纹不变。新曲线的写入、恢复及异常回滚已在隔离 Lua 宿主中测试，尚未在真实工程执行这些新增写入。验证不涵盖所有声库、复杂工程、ASIO 路径或原生撤销操作，也不证明听感改善。真实云模型请求与音频听评尚未完成验证。 仓库不分发私人测试工程、录音、截图或本地验收记录。

隐私与数据管理

默认数据目录及其会话、音频、操作日志、备份和 IPC 内容均属于本机私人数据。模型平台配置和模型缓存中的连接身份摘要使用 Windows DPAPI 加密；模型目录名称、会话、歌词摘要、音频、工程备份和操作记录并非全部加密，应按作品及个人资料管理。DPAPI 保护与当前 Windows 账户绑定，不能保证把文件复制到其他机器或账户后仍能解密；迁移时请重新配置密钥并按需刷新目录。

只有用户发送消息、提交 A/B 听评或主动刷新模型目录时，才会访问配置的供应商。纯文字请求包含当前文本和受限文字历史；勾选时还包含安全选区摘要。音频仅来自本次明确选中的附件；本地上传、录音、保存设置本身不会上传给模型。自定义 API 地址会收到对应凭据与请求内容，请使用可信服务。MCP 客户端可读取工程信息及显式请求的录音，客户端怎样转交给模型由其自身决定。

永久删除仅清理选定的本地资料，不级联工程备份、其他会话、操作日志或已经发送给供应商的内容；历史消息仍可能保留附件名称。它不是磁盘安全擦除工具。发布问题、截图或代码改动时，请移除真实密钥、私人路径、歌曲内容和运行数据，详见 安全与隐私说明。

常见问题

• 桥接未连接： 确认 SynthV 已打开，并从脚本菜单启动当前安装的 SynthV Assistant；移动项目或更换数据目录后需重新打包安装。

• 无法录音或没有声音： 确认 Windows build、.NET 10 运行时及采集器构建成功，等待 SynthV 合成完成，检查当前混音及音频输出路径。不会自动改用麦克风或全系统录音。

• 模型请求失败： 检查协议、模型、密钥和端点；聊天要求 SSE 流式响应，音频附件要求对应音频输入格式。已配置状态不等于云端连接验证。

• 应用超时或结果未知： 先检查 SynthV 实际状态，必要时撤销，再重新读取选区和规划；不要立即重复应用。

• 端口被占用： 使用 scripts/start.ps1 -Port 8766 等其他本地端口，不要终止不相关进程。

更多实现细节见 架构说明，模型及音频限制见 模型与音频说明，模型任务约定见 内置提示词规范，界面开发见 前端设计与实现规范，开发与问题反馈见 贡献指南。

许可证

本项目以 MIT 许可证 发布，Copyright (c) 2026 blockshy。随源码提供的第三方组件保留各自版权与许可，详见 第三方声明。Synthesizer V、声库、模型服务及其他外部软件不属于本项目授权范围。