SVIXAGENT

以 DSH（DeepSeek Harness）为底层、用对话操作 Synthesizer V Studio / Instrument X 的智能助手。

📦 仓库名 SVIXAGENT = Synthesizer V + Instrument X + AGENT；产品名 AKDAgent（安装包 / 程序名 / 数据目录都用后者）。

你说人话，它替你动手：看得懂你的工程（当前在哪条轨/组、选中了哪些音符、伴奏是什么和弦）， 并直接改工程里的音符、音高线、参数与织体。

平台	宿主	规模
Windows 10+（64 位）· macOS 11+（Apple Silicon）	Synthesizer V Studio SV1 / SV2 · Instrument X（另支持第三方宿主 ACE Studio）	53 个 MCP 工具 · Lua 桥 32 个 op

⬇️ 下载：见 Releases —— Windows AKDAgent-<版本>-x64.exe · macOS AKDAgent-<版本>-arm64.dmg（更新方式 = 重新分发安装包；客户端不出网、不自动检测、不自动下载，无遥测）。

目录

• 这是什么
• 一、开始使用　· 运行要求 / 安装 / 配 API 密钥 / 部署桥 / 启动 / 设置项
• 二、组件　· 桥 / 悬浮球 / 侧栏面板 / 语音输入 / 语言（两套）
• 三、功能　· 音频分析对轨 / 工程生成 / 音符编辑 / 旋律和声 / 歌词 / 音素咬字 / 音高 / 参数 / IX 专属 / Flat 声库
• 四、注意事项与常见问题
• 反馈与联系
• 许可与第三方　· English

---

这是什么

AKDAgent 是一个以 DSH 为底层、用对话操作 Synthesizer V Studio / Instrument X 的智能助手。 （也支持第三方宿主 ACE Studio —— 机制不同，单独一章见 §五。）

你可以直接用自然语言表达你想做什么：

• 「这段音高线按抒情处理画柔一点」
• 「这两小节补个弦乐铺底」
• 「把歌词按时间轴对上」

它看得懂你的工程（当前在哪条轨/组、你选中了哪些音符、伴奏是什么和弦）。

---

一、开始使用

1.1 运行要求

项	要求
系统	Windows 10 及以上（64 位）；macOS 11 及以上，Apple Silicon（M 系列芯片）（Intel 机型不支持）
宿主	需已安装 Synthesizer V Studio（SV1 / SV2 都支持）或 Instrument X（侧栏面板需要 SV2 / IX 1.0.0 及以上）
磁盘	安装包约 380 MB，装完展开约 1 GB（macOS 版同量级）；语音输入模型按需下载、三档可选，另需 0.02～0.22 GB（不装也能用，只是没有语音输入；档位见 §2.4）

macOS 看芯片，不看机型：「关于本机」里写 芯片 Apple M…（M1 及之后）就能用；写 处理器 Intel 就不支持。 能用：Apple Silicon（M 系列）—— 2020 年 11 月起的那批；不支持：Intel 机型（2019 年及更早发布的全部 Mac，加上 2020 年的 Intel 型号：27 吋 iMac、13 吋 MacBook Pro、13 吋 MacBook Air）。 原因：ONNX 运行时不提供 Intel(macOS/x86-64) 的二进制；且 Apple 已宣布 macOS 26 是最后一个支持 Intel Mac 的系统。

1.2 安装

Windows：

1. 双击 AKDAgent-<版本>-x64.exe（或 .msi），按向导走 —— 安装位置可以改，默认装到 %LOCALAPPDATA%\Programs\AKDAgent
2. 按用户安装、不需要管理员权限（所以不会弹 UAC）；装完桌面与开始菜单会有快捷方式
3. 启动客户端（启动后桌面上会有悬浮球）

卸载：控制面板/设置里的「AKDAgent」，或安装目录下的 Uninstall AKDAgent.exe。 卸载器可能会问"是否删除应用数据"，选否即可保住设置（%APPDATA%\AKDAgent）；你自己的 DSH 数据（~/.dsh）不受影响。

macOS：

1. 下载 AKDAgent-<版本>-arm64.dmg，双击打开 → 把 AKDAgent 拖进「应用程序」（zip 版也行：解压后同样拖进去）
2. 首次打开：右键 → 打开（安装包未签名/未公证 ⇒ 直接双击可能被 Gatekeeper 拦；或在「系统设置 → 隐私与安全性」里点「仍要打开」）
3. 启动后菜单栏会出现图标、桌面上会有悬浮球

卸载：把「应用程序」里的 AKDAgent.app 拖进废纸篓即可。 你的数据在 ~/Library/Application Support/AKDAgent（设置/语音模型）与 ~/.dsh（会话），拖走 app 不会删它们。 语音输入首次启用需要授予麦克风权限；未签名的包有时会被系统反复问 —— 在「系统设置 → 隐私与安全性 → 麦克风」里勾上 AKDAgent 即可。

1.3 配 API 密钥（模型提供方）

设置 → 模型：选一个提供方，填它的 API 密钥即可用它的模型。

• 内置 DeepSeek 卡片：直接在卡片里的密钥框填入（保存后不会再每次弹窗）
• 12 个内置预设（点一下加一张卡片，各自填自己的密钥）：openai · anthropic · google · groq · mistral · openrouter · xai · moonshotai · deepseek · cerebras · together · huggingface
• 自定义提供方（+ 添加自定义提供方）：填密钥环境变量名 · 接口协议（如 openai-completions / anthropic-messages）· 服务地址；密钥也可以直接填

不想填密钥？订阅账号也能直接用 —— 同一页最下面的「订阅登录」区，点对应提供方的「登录」按钮：

1. 浏览器里完成授权（或按提示把设备码填到验证页上；换机器登录时把授权码粘回来也行）
2. 完成后凭据存在本机凭据库，该提供方的模型就能用了；「登录」按钮旁那行会如实写出进行中 / 已登录 / 失败原因

支持六家：ChatGPT Plus/Pro（OpenAI Codex）· Claude Pro/Max（Anthropic）· GitHub Copilot · Kimi 编程套餐 · xAI · OpenRouter。

• GitHub Copilot 会先问一次企业域名 —— 不是 GitHub Enterprise 就留空
• 清单是空的？宿主启动后约 1.5 秒才注册完 ⇒ 点一次「刷新清单」；若助手刚升级过，重启一次助手让它重写宿主配置
• 清单里没有的提供方 = 这个版本没带它的登录流（例如 radius），那条路走上面的 API 密钥
• 凭据只落在本机（助手自己的凭据库），不上传

如果本机已经装了 DeepSeek Harness（DSH），助手会直接沿用它的密钥与设置，不用再填一遍。

⏳ 待补：截图。

1.4 把桥部署到宿主

设置 → SV 集成：添加宿主的 scripts 目录（可以加多个版本，也支持「自动检测」）→ 点「一键部署到全部目录」。 部署会把桥脚本放进该目录的 Agent\ 子目录，并在各 SV 根目录建好工作文件夹。

1.5 启动：打开悬浮球 + 在宿主里运行桥

1. 打开悬浮球（桌面常驻）或宿主里的侧栏面板 —— 出现「AKDAgent」
2. 在宿主里运行 Agent → AKDAgentBridge.lua
3. 面板顶部显示 桥：在跑 ⇒ 接通，可以开始对话了

为什么要手动跑一次：桥跑在宿主内部、负责读写工程与文件，而侧栏面板自己没有文件权限（宿主的安全限制）⇒ 面板无法替你启动桥。跑过就一直活着，直到关闭宿主；下次再进宿主还要跑一次。顶部显示"过期 / 离线"就是没跑、或跑过又被关掉了。

1.6 设置项一览

区	有什么
模型	提供方列表 · 内置 / 自定义提供方 · 密钥 · 接口协议与服务地址 · 订阅登录（六家用订阅账号免密钥，见 §1.3）
对话设置	语言（简体中文 / 繁體中文 / English / 日本語）· 推理强度 · 语音输入（选模型，见 §2.4）
SV 集成	桥脚本来源 · scripts 目录（可多个版本） · 部署（一键部署）· SV Flat 版（nofs JSON 编辑器）（见 §3.10）
运行状态	助手服务的运行状态 · 相关操作 · 悬浮球状态

---

二、组件

2.1 桥（跑在宿主里的脚本）

桥就是连接宿主与助手的那个脚本 —— 助手要读你的工程、要写音符，都得经过它；两侧靠本机文件交换信息（不走网络）。

① 你说话（悬浮球 / 宿主侧栏面板）
        │
        ▼
② Electron 客户端（悬浮球 · 设置 · 密钥窗）
     ├─ 内嵌 DSH 运行时（node）──► 模型 API：想清楚要调哪个工具
     └─ MCP server（resources/server/dist/index.js，stdio 子进程）
              │
              │ ③ 文件通道（本机 %TEMP%，不走网络）：
              │    akdagent-{req,res,hb,log}-<host>.json
              ▼
④ Lua 桥 AKDAgentBridge.lua —— 跑在宿主里的脚本，轮询取请求
     ├─ 读写工程：音符 / 歌词 / 参数 / 自动化 / 速度标记…
     └─ 侧栏面板：宿主的 SidePanelSection ⇄（project scriptData）⇄ 客户端
              │
              ▼
⑤ 宿主 SV / IX 里的工程

• 随安装包分发，在 设置 → SV 集成里一键部署到宿主的 scripts 目录；在宿主里运行后常驻
• 同一时间只支持 1 个 SV + 1 个 IX（见 §4.1）

2.2 悬浮球（对话窗）

悬浮球是你平时跟助手对话的窗口 —— 常驻桌面，点开即用。

• 支持语音输入（§2.4）
• 托盘 / 悬浮球菜单：新会话 · 隐藏到托盘
• 与侧栏面板同步

2.3 侧栏面板

侧栏面板是宿主里那块对话面板 —— 借用 SV2 / IX 自带的侧边栏：聊天、提问、选项都在里面点，不用切窗口。

• 信息框 · 输入框 · 单选 / 多选选项 · 补充说明框 · 确认 / 跳过 / 停止 / 刷新
• 单选点一下即提交；多选逐个勾选后再确认；跳过 = 让助手自己决定
• 一次只显示一道题，答完即消失
• 顶部实时显示 桥 / 悬浮球状态，离线时给"怎么开"的提示

2.4 语音输入

通过语音快捷输入内容（全程在本机识别，不上传）

• 三档本地模型：轻量 24 MB（中文，边说边出） · 标准 200 MB（中英双语，边说边出） · 精确 217 MB（中英 + 方言，说完再出，最准）
• 设置页可切换、可看下载状态

2.5 语言（两套，互不影响）

语言是两套独立设置（都在 设置 → 对话），改一套不会动另一套：

• 客户端界面语言：悬浮球 / 设置窗 / 托盘 / 密钥窗这些客户端界面的文案 —— 四语可选（简体中文 / 繁體中文 / English / 日本語），首次启动按系统语言自动选，设置里随时改
• DSH 界面语言（内嵌 DSH 的 locale.preference）：决定模型回复用哪种语言，以及 DSH 自己的网页界面 —— 与上面的客户端界面语言各管各的

2.6 附件：拖文件 / 粘路径

把文件交给助手，最省事的一步 —— 拖进去就行。（助手几乎所有重活都是路径入参：乐谱导入、音频分析 / 分离、工程文件改写、ACE 侧的各种 --path。）

• 拖进悬浮球：从资源管理器把文件（或文件夹）拖到对话窗口，附件条上会列出它们
• 粘路径：把一个路径直接粘进输入框，也会变成附件
• 发出去的只有路径：消息里带一段 附件（绝对路径）： 清单 —— 客户端不读文件内容（两处例外见下两条），也不绕过任何检查（工具侧该预览的预览、该确认的照旧）
• .pdf 会自动渲染成图片：识谱引擎吃的是位图，所以拖进来的 PDF 先在客户端渲成 PNG（300 DPI、单次最多 20 页，落在客户端工作目录的 omr-render\ 里），附件条里换成这些图片的路径并标注「PDF 已渲染成 N 张图」。渲染失败不静默：保留 PDF 并把原因写在附件条上
• .m4a 等音频会自动转成 WAV：内置解码器只认 MP3 与 WAV（把 m4a/AAC 直接喂进去只会得到一段噪声），所以 m4a/AAC、FLAC、Ogg、WebM 这些先在客户端用自带的 Chromium 解成 16bit WAV（保持源采样率，服务端再转 44.1k；落在客户端工作目录的 audio-convert\ 里），附件条里换成 WAV 路径并标注「音频已转成 WAV」。⚠️ 超长音频只转前 30 分钟（附件条会写明）。转换失败不静默：保留原文件并把原因写在附件条上
• 上限 20 个；发送成功才清空附件条，失败会保留，可以直接重发

拖了文件却忘了打字时不会静默丢弃：输入框会聚焦、附件条闪一下提醒你"还没发出去"。 截图直接喂给模型暂未做 —— 要喂图请选支持图片输入的模型。

---

三、功能

共 44 项，按主题分 11 类。哪个功能在哪个宿主可用有差异，见 §4.1；ACE Studio 单列一章（§五）。

3.1 音频分析处理（含对轨）

这类帮你读懂音频、并把伴奏和工程对上线 —— 速度、调性、和弦、情绪、人声与伴奏分离。

• 分析音频：速度 / 节拍 · 调性 · 和弦 · 情绪（喜 / 宁静 / 愤 / 悲伤 四类）· 音高中位数（可只分析某一段）—— 很快：3 分钟的伴奏十秒上下出结果
• 分离与提取：人声 / 伴奏分离（在你本机跑，不联网，可分成两次各取更干净的一侧 · 最慢，约 3 倍音频时长：3 分钟的歌约 9 分钟，两侧都取要跑两遍 ⇒ 差不多翻倍）· 从中提取音符（相当于人声转谱；默认用轻量模型，要更准的可以说一声换更精确的 · 与分离同量级，长曲子建议先只分析某一段或先把音频截短）· 任意音频转 44.1 kHz WAV（纯解码，很快）
• 对轨：测出速度与第一拍位置，把伴奏轨对齐到小节线（或第一个音符）· 按伴奏的实际速度变化逐段打速度标记（适合速度有漂移的曲子）—— 测速与打标记都很快（同分析类）；⚠️ 按实时 BPM 打速度标记依赖 SV2，SV1 上暂不可用

3.2 工程生成、处理

这类帮你直接产出工程文件、或直接改工程文件 —— 不必开着宿主也能做（宿主开着时也照样做）。

• 直接生成工程文件：内部包含了完整的 .svp、.ixp 数据结构，可以根据结构生成新的工程。
• 直接编辑工程文件：api 做不到的部分功能，可以直接通过修改工程实现。
• 导入乐谱（MusicXML）：把现成的乐谱搬进工程 —— 音符 / 时值 / 歌词按谱面落进去，技法与力度也照谱面标注映射；谱面自带的速度只做汇报、不自动套用；复调（多声部 / 和弦）默认拒绝（会算错音位），确要导再显式说明

3.3 音符编辑

针对"手工做很烦、或索性做不到"的编辑 —— 按条件挑、整批套同一规则、要算相对关系的。 （单纯移调那种两个快捷键就完事的，助手当然也能做，但那不是这一节的意思。）

• 按条件挑音符再动手（条件说一声即可，助手在宿主里一趟跑完）：
  • 「把时值短于 16 分音符的都拉长到 16 分」
  • 「超出这条轨音域的音全部整八度挪进来」
  • 「这几段的参数（响度 / 张力 / 气声…）按第一段对齐」
• 整批套同一规则：多条轨 / 多个组 / 整段范围一次做完 —— 手工要点很多遍，还容易漏

3.4 旋律和和声

这类帮你写旋律，也给已有旋律配和声 —— 从零生成一段，或复核你写好的一段。

• 生成旋律：给调性 / 情绪 / 和弦进行 / 小节数即可；内含动机发展、分句与气口、句末终止、单一高点、强拍落和弦内音；可选伴奏琶音，能导出 .mid
• 复核旋律：不留气口 / 六度以上大跳 / 单音重复 / 大段短音符 等判据，出一份建议清单
• 生成和声：按主旋律 + 伴奏调性生成三度 / 六度等和声部，写进新组或新轨

3.5 歌词

这类帮你把词安到音符上，并检查唱出来会不会怪 —— 对位填词，外加倒字 / 谐音 / 韵脚 / 词格的复查。

• 对位 / 填词：中文逐字、英文按词；有 LRC 时间戳时可按时间对齐；也可整轨写入，可以通过sv自带的音频转录辅助对轨填词

• 歌词复核：倒字（旋律走向与字调不合）· 谐音（容易听成别的字）· 韵脚（首句漏押 / 段内换韵 / 虚字充韵脚）· 词格（字数与音符数是否对得上）

• 辅助歌词生成：给主题 / 情绪 / 风格（或结合已有旋律的字数与气口）写一版词 —— 段落结构、押韵、意象与词格按规范来；写完直接接上面的对位填词落进工程，不用来回换工具

• 歌词怎么填（按你手上的材料选一条）：

  1. 有 LRC 时间戳 ⇒ 按时间把字对到对应音符上
  2. 只有干声 / 伴奏音频 ⇒ 先从音频提取一条参考轨（音符的起止与音高），再照它把词逐字对上去
  3. 什么参考都没有 ⇒ 直接把词给助手，它先按现有音符顺序 / 小节给你一版，你再改

3.6 音素咬字（含说唱专项）

这类帮你抠唱出来的细节 —— 辅音收边、音素替换、混合语种、说唱的声调与重音。

• 读宿主的计算结果：音高曲线 · 说唱的重音与语调 · 每个音实际用的语种（宿主一次算不完，助手会自动等它算完）
• 音素候选：某个字唱得不对（糊、含糊、尾音怪）时，助手按这个音符实际在用的语种给出可替换的音素——元音按"同族"、辅音按"发音相近"排，只给最像的几个（该语种里没有相近的会如实说明，而不是硬凑）
• 批量替换音素：把一批音符的音素按规则换掉（例如某段里统一把 u 换成 U，或把某个辅音换成更清晰的写法）；默认只给计划、不写工程，你确认后才落盘，写完会逐音回读
  • 清单外的音素直接拒写（避免写出唱不出来的音；不同语种/声库的写法差异助手会提示）
  • ⚠️ 只想改一个音素、却要跨语种时，助手会提醒你先把那个音符拆成两个 —— 因为改语种会让这个音符的全部音素重算
• 辅音收边：短音符后面那个音的起首辅音容易"吃掉"前一个音 ⇒ 助手扫出来并给收边方案，默认只预览不写
• 混合语种：一首歌里混了多种语言时，按语义判断并只改少数派音符的语种，默认只预览不写
• 说唱专项：按词判定普通话声调（多音字按词定音），逐音符写入说唱重音，默认只预览不写

3.7 音高

这类帮你画音高线，让唱腔有起伏、有情绪。

• 画 / 改写音高线：自动适配你的宿主版本；内置音高线画法与方向修正。默认只画算出来的重音音符（按风格判定，非重音位保持"自动"、一点不动）—— 要把整段、或你选中的那一片都画满，明说一声就行
• 彩蛋：用音高线画画（SV2）：每条音高线单独渲染、还能叠很多条 ⇒ 一条曲线画一笔，把图案或文字的轮廓映射成"时间 × 半音"就能画进钢琴窗；画布会锚定在组里的音符上、并夹进你当前可见的音高范围（不然就画到看不见的地方）
• 加装饰音：前倚音 · 后倚音 · 波音 · 回音 · 音尾音阶行进 · 反向预备 · 滑音 —— 说一句就加，一次可以套好几个音符；还能顺带配上配套的动态变化（前倚音"挖个小坑"、后倚音尾部渐弱、音尾行进每步递减）

3.8 参数

这类帮你调音色和唱法 —— 响度、张力、气声这些用对话直接说就行。

• 参数（响度 / 张力 / 气声 / 发声 / 性别 / 音区偏移 / 开口度 / 颤音倍率 …）用对话直接说即可（例如"这一段张力拉高、气声降下来"）
• 颤音倍率可以突破界面里"颤音幅度"的上限，是做大颤音的常用手法
• 直接写参数曲线：张力 / 响度 / 气声 / 发声 / 性别 / 颤音包络 / 音区偏移 —— 按时间点写进工程；写前按取值范围夹住（不会写出让宿主出问题的量级），写完回读核对

3.9 IX（Instrument X 专属）

这类是 Instrument X 专属的伴奏织体与演奏技法 —— 和弦与伴奏型在这里生成；拨奏、弱音、震音这些可以自动标，也可以整段设。

• 铺和弦：从伴奏音频里扒出和弦，按柱式 / 分解 / 琶音写进工程（和弦来源也可以是工程里已有的音符、或你直接给的进行）
• 按乐器铺织体（伴奏型）：弦乐 5 档 / 管乐 8 档；8 种铺法（柱式 · 分解 · 琶音 · 长音铺底 · 低音走句 · 固定音型 · 重复乐句 · 照你写好的首小节模仿）；自动帮你留换气口、做换弓、把超出音域的音整八度挪进来；一律新建组，不动你原有的音符
• 演奏技法自动标注：内置 10 条走向规则（句末长音 → 保持音 · 大跳进入 → 滑音 · 乐句最高点 → 重音 · 句末回落 → 下滑 · 同音重复 → 震音 · 两音交替 → 颤音 · 同向级进 → 圆滑 · 短音连跑 → 断奏 · 萨克斯上滑 / 下滑）+ 6 个风格档调阈值
• 写织体 / 和弦时也能顺手带上技法
• ⚠️ 写入后如果听不出效果，多半是该乐器不支持这个技法（换技法或换乐器轨再试）；被写过的音符会变成"手动指定"，宿主不再自动决定它的技法
• 其它 IX 差异：IX 允许音符重叠（SV 的人声组不允许）· IX 的主组不能写音符（助手一律新建组）

3.10 Flat 声库编辑

这类帮你改声库本身 —— 查看、新建、微调风格，或从一个声库移植到另一个。

• 设置页的编辑器：SV Flat 版（nofs JSON 编辑器）（设置 → SV 集成）——直接查看 / 修改声库的配置文件
• 对话侧也能做：列出已装声库与各自的风格（按 vocoder 分组）· 看某个声库的风格详情 · 把一个声库的风格移植到另一个（要求同一 vocoder）· 新建风格（基于已有风格或随机）· 微调风格（改动前自动备份）

3.11 乐谱识别（五线谱 / 简谱 → 工程）

把谱子变成工程里的音符 —— 两条路：**电子谱（MusicXML）**直接导，谱子图片用内置识谱（OMR）。

• 直接导 MusicXML：音符 / 时值 / 歌词按谱面落进去，技法与力度也照谱面标注映射（完整说明与护栏见 §3.2「导入乐谱」）
• 图片（PNG / JPEG）：已内置识谱 —— 一张谱子图片就能认成 MusicXML，再按 §3.2 导进工程（引擎 = 悦谱 Dolce，MIT，全本地离线；MCP 工具 sv_omr_image）。识别覆盖率（没归属的图形 / 时值能凑满的小节）会如实报给你，认得不全就换更高清的原图；PDF 会自动渲成图片（拖进来就渲：300 DPI、单次最多 20 页，见 §2.6）
• 简谱 / 数字谱同理：能导出 MusicXML 的工具都能接
• ⚠️ 谱子在网址上的先下载到本机（导入只认本地文件）；复调（多声部 / 和弦）默认拒；单次上限 512 个音符（大谱子分段导）
• 多页谱：逐页导（每页一次），页与页之间用偏移接上（导入工具有 offsetQ，单位是拍），组名要给不同值 —— 同名会把上一页替换掉

为什么只认本地文件：要保证"你预览的那一份"和"写进工程的那一份"是同一个文件（预览之后文件被改过会被拦下）。 这条路的入口和 §3.2 是同一个工具，所以它不额外占"功能项"计数。

---

四、注意事项与常见问题

4.1 注意事项

这几条是"提前知道能少走弯路"的限制 —— 大多来自宿主本身，不是助手的选择。

项	说明
一次只开一个同类宿主	同一时间只支持 1 个 SV + 1 个 IX；同时开两个同类宿主会互相抢请求
桥每次进宿主都要跑一次	桥是跑在宿主里的脚本，而侧栏面板自己没有文件权限、没法替你启动它；顶部显示"离线 / 过期"就是没跑、或跑过又被关掉了（见 §1.5）
SV1 没有侧栏面板	侧栏是 SV2 / IX 1.0.0 起才有的机制；SV1 上只能用悬浮球
SV1 部分能力缺失	例如按实时 BPM 打速度标记；要这些请用 SV2
IX 的技法默认"只给计划"	先出计划给你看，确认后才写工程；只覆盖命中的少数音符，其余留给宿主自带的 Smart Articulation（不越权接管）
IX 的技法"写得进 ≠ 用得上"	听感是唯一判据；听不出效果就换技法或换乐器轨再试

4.2 常见问题（排障）

遇到"没反应 / 不对"先在这里对一下 —— 按现象查；查不到就直接问助手。

现象	怎么查 / 怎么办
面板显示桥"离线 / 过期"	① 在宿主里运行过桥吗（每次进宿主都要一次）② 跑完又被关掉了吗 ③ 设置 → SV 集成里的 scripts 目录填对了吗
对话没反应 / 提示"桥不在线"	先让助手探一下宿主（它会报宿主名与版本）；不在线就回到上一条
面板里点了选项没反应	面板一次只出一道题，答完即消失；可点「刷新」；仍不行看顶部两行状态
装了新版，好像跑的还是旧桥	设置 → SV 集成 → 一键部署覆盖各目录，然后在宿主里重新运行一次桥
换了宿主（SV ↔ IX）后不对	明确告诉助手"现在操作的是 IX / SV"；技法类功能只在 IX 有
导入乐谱被拒	报错会写原因：路径或网址不合规 · XML 里有脚本声明 · 音符超过 512 · 是多声部 / 和弦 · 还没确认有权使用 · 文件在预览后被改过（重跑预览即可）
谱子在网址上，想直接导	这一环只认本地文件（要保证"你预览的那份"和"写进去的那份"是同一个文件）：先下载到本机再导入；让助手替你把文件下下来落盘再导，也可以 —— 仍走同一条「预览 → 校验 → 写入」流程
订阅登录点了没反应 / 清单是空的	① 宿主启动后约 1.5 秒才注册完 ⇒ 点「刷新清单」② 刚升级过就重启一次助手（要新宿主才读得到）③ 换机器登录（Claude / ChatGPT / OpenRouter）时，授权码要粘回来，别关掉那个提问框
写了技法但听不出来	该乐器可能不支持这个技法；换技法或换乐器轨再试
语音输入起不来	设置 → 语音输入里看模型是否下载完；页面上会写明原因
宿主升级后提示"本包文档可能过期"	这是离线比对包内记录的宿主版本的结果（不联网）⇒ 下载最新安装包即可
ACE 里没反应 / 提示 CLI 找不到	ACE 是另一套机制（不走桥）：确认 ACE 在跑、开着 External Agent Access、装的是 2.1.8+ 且 acestudio-cli 能找到（详见 §五）

---

五、ACE Studio（第三方宿主）

AKDAgent 也能在 ACE Studio 里干活 —— 但 ACE 与 SV / IX 机制完全不同，先看清这四条再动手。

5.1 前提与「不走桥」

• 需要 ACE Studio 2.1.8 及以上、并打开 External Agent Access；它自带命令行 acestudio-cli（0.17.0）
• ⛔ ACE 不走我们的桥：没有 AKDAgentBridge.lua、没有侧栏面板、没有心跳文件 ⇒ ACE 用户别去跑桥；球 / 设置页上的「ACE 在线」是另一套判据（见 §5.4）
• ✅ 可以同时用：一个 SV + 一个 IX + 一个 ACE 互不抢请求

5.2 在 ACE 里能做什么

• 读：工程信息 · 轨道 / 片段 / 音符 / 歌词 · 音素（含时长与是否被"钉住"）· 人声参数（张力 / 气声 / 能量 / 动态 …）· 作业与生成结果
• 写：音符与歌词 · 音素替换与时长微调 · 人声参数曲线 · 音色 / 声库切换 · 导出音频 / 视频 / MIDI
• 人声音高线：ACE 的命令行没开放这条 ⇒ 只能改工程文件（pitchDelta）再让 ACE 重新打开工程；曲线 / 锚点 / 颤音三种画法都支持，但重载有明显提示 ⇒ 只值得做批量改动

5.3 与 SV / IX 的三处不同（都踩过）

项	说明
参数名 ≠ 文件字段	例如 dynamic 存在 vocalControls.__dynamic；air 存在 mambaBreathiness（不是 mambaAir）
两代引擎两套参数	v2（singing-mamba）才有 dynamic，尺度 0..1；v1（verse24）是围绕 1.0 的乘数（air 0.2–2.5 …）⇒ 跨代抄数值一定错
越界一律拒绝	ACE 不夹取，越界直接报参数错（我们 SV 侧相反：夹到边界并回报）

5.4 状态与排障

• 悬浮球 / 设置页会显示 ACE 在线 / 离线（判据：ACE 在跑 且 开了 External Agent Access）；离线时球会给提示
• 「CLI 找不到」：确认装的是 ACE Studio 2.1.8+，acestudio-cli 与其同目录（或用 ACESTUDIO_CLI 环境变量指定路径）
• 改了工程文件没生效 ⇒ ACE 里那份还是旧的：让它重新打开该工程

---

反馈与联系

B 站主页：space.bilibili.com/12131593　·　邮箱：[email protected]　·　GitHub 仓库：Akunda123/SVIXAGENT

说清这三样最省事：① 现象（有截图更好）② 你刚做了什么（从哪一步开始不对）③ 宿主是 SV 还是 IX、什么版本。

客户端不出网、不自动上报任何数据（无遥测）—— 反馈只有上面这几个入口。

---

许可与第三方

• 本项目自身的开源许可：MIT（见 LICENSE）
• 随安装包分发的知识包 = knowledge/docs + tools；技能随内嵌运行时一并分发
• 上游内容只做摘要改写并标注来源；第三方许可声明与各依赖 LICENSE 正文随安装包分发（见 THIRD-PARTY-NOTICES.md 与 licenses/）

---

English (brief)

AKDAgent is an AI assistant built on DSH, driving Synthesizer V Studio / Instrument X through conversation. 1 Getting started · 2 Components · 3 Features · 4 Caveats & FAQ

---