AKDAgent

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

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

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

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

目录

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

这是什么

AKDAgent 是一个以 DSH 为底层、用对话操作 Synthesizer V Studio / Instrument X 的智能助手。

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

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

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

一、开始使用

1.1 运行要求

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）· 服务地址；密钥也可以直接填

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

⏳ 待补：截图。

1.4 把桥部署到宿主

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

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

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

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

1.6 设置项一览

二、组件

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 自己的网页界面 —— 与上面的客户端界面语言各管各的

三、功能

共 44 项，按主题分 10 类。哪个功能在哪个宿主可用有差异，见 §4.1。

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）· 新建风格（基于已有风格或随机）· 微调风格（改动前自动备份）

四、注意事项与常见问题

4.1 注意事项

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

4.2 常见问题（排障）

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

反馈与联系

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