AKDAgent 1.0.3（Windows x64 · macOS arm64）

AKDAgent 1.0.3（Windows x64 · macOS arm64） —— 修「AKDAgent 夺舍了 DSH」：从此只写自己的家，用户自己那份 ~/.dsh 一个字都不动；顺带修掉一个会静默吃掉用户 key 的合并 bug。

版本号说明：本轮内容只动了客户端与 MCP server；
桥（1.0.2）与面板（1.0.2-js）内容未变 ⇒ 保持原版本号（不改桥就不必重跑桥）。
产品 / server / 作业手册（playbook）升到 1.0.3。

1️⃣ 与用户自己的 DSH 彻底分离（用户报「夺舍了 dsh」）

AKDAgent 自带一个 DSH 宿主，数据根本来就是隔离的（~/.dsh-akdagent），但客户端仍会读写用户自己那份 ~/.dsh。四条全切断：

	以前	现在
A 凭据	填 key 写 ~/.dsh/.credentials.yaml（没有就 mkdir ~/.dsh）	只写 ~/.dsh-akdagent/.credentials.yaml；用户那份只在"我们还没有 / 缺某个 key"时单向只读导入（只增不改）
B 自愈	启动时就地规范化改写用户的凭据文件（还留 .bak）	不写源、不留 .bak、不建 ~/.dsh；自愈只作用在我们自己那份
C 设置	语言等设置整份读-改-写 ~/.dsh/settings.yaml	只写 ~/.dsh-akdagent/settings.yaml；源只读回退。MCP server 找脚本目录的读序也改成 $DSH_HOME → ~/.dsh-akdagent → ~/.dsh（末级只读）
D 环境变量	拉起内嵌宿主时 {...process.env} 原样透传	先清掉继承来的 DSH_*，只用我们设的 DSH_HOME / DSH_BUNDLED_SKILL_DIR

代价（明确告知）：两边不再互通 —— 你在 AKDAgent 里填的 key / 改的语言不会再回流到你自己的 DSH，反之亦然。要两边都配，就各填一次。

2️⃣ 修一个会静默吃掉 key 的合并 bug

凭据同步里有个"合并"逻辑，它的 refs 是整份取源的 —— 那在"客户端只写源"的年代是对的。
改成"客户端写我们那份"之后，一旦出现「源里有 key K、我们自己有 key J」，合并就会把 J 丢掉（界面不报错，用户只是某天发现 key 没了）。
现在改成取并集、以我们那份为准；并加了行为守卫（反例验证：改回整份取源 ⇒ 守卫当场亮红）。

3️⃣ 守卫与台账

• 新增 tools/check-dsh-separation.cjs：A/B/D 静态判据 + 真跑一遍（造一个假的"用户 ~/.dsh"⇒ 断言源目录逐字节未变；再验证"我们自己的 key 不丢"）+ 跨组件读序。反向验证：指回修复前那份 ⇒ 8 条 FAIL（含 .credentials.yaml.bak 这种实锤）
• check-credentials-doc / check-credentials-sync 判据同步反转（源必须未被触碰）
• 顺手修了一个陈旧守卫：test-settings-model-ui.cjs 还在断言"只有 DeepSeek 能增删模型"（09-25 已改成两种都能编辑）⇒ 一直红；现按现行实现重写，并加了"pi-ai 的增与删各走 setPiProviderFields"的计数断言

安装

• Windows：下载下面的 AKDAgent-1.0.3-x64.exe（未签名 ⇒ SmartScreen 可能提示，选「更多信息 → 仍要运行」）
• macOS（Apple Silicon）：.dmg / .zip 由 mac CI 稍后挂到本页

AKDAgent 1.0.2（Windows x64 · macOS arm64）

AKDAgent 1.0.2（Windows x64 · macOS arm64） —— 修「一填 API Key 就闪退」、给 SV 集成加 HTML 护栏、把「宿主弹脚本错误框把桥卡死」这类事故从预防 / 取证 / 恢复三面堵住。

版本号说明：1.0.2 的功能内容 = 1.0.1 上陆续修好的四件事，这次把产品 / 桥 / 面板 / 改过的技能统一升到 1.0.2
（此前 1.0.1 的补丁资产 -keyfix.exe 与 2026-09-27 替换过的 1.0.1 Windows 包，内容都已被本版包含）。

这一版修四件事

1️⃣「一填 API Key 就闪退」（用户报「1.0.1 过了一会就闪退」）

真因：客户端把 key 写成了宿主不认的凭据文档格式（顶层 DEEPSEEK_API_KEY）⇒ 宿主启动时直接报
credentials-local: unknown top-level key 退出 ⇒ 客户端约 0.5 秒后跟着退。
现在：写入侧只写合规格式（version/refs/records），启动时自动治愈存量坏文件（就地规范化 + .bak），
并把被拒收的那份隔离留证（…rejected-<时间戳>）。

2️⃣ SV 集成的两个交互护栏（用户要求：提醒/确认一律 HTML，不用系统原生框）

• 没指定 SV scripts 目录 ⇒ 每个客户端版本提醒一次，并打开三步配置向导
  （说明 → 自动检索目录并勾选 → 一键部署）
• 往 SV1 / OPSV 这类没有侧栏的宿主部署面板前 ⇒ 先确认（那边装面板不生效，
  还会在脚本菜单里多出一个「点了可能报错」的项）

3️⃣ 宿主里弹「脚本错误」把桥卡死（用户真机截图：setAttributes: 无效的输入类型。）

这类错误框是模态的 —— 框一弹宿主主线程就停，桥的轮询链随之死，而 pcall 拦不住宿主弹的框。
所以只能「预防 + 取证 + 恢复」：

• 预防：AI 写脚本进宿主之前预检 —— 点调用（JS 写法）、非表实参、setAttributes 的键与值
  （按官方 Note#getAttributes 文档查「键属不属于这个宿主 / 值类型对不对」，IX 豁免）、写错宿主的字段、
  crash 清单（Automation#getPoints 族、remove(单参) 等）一律拒，并直接给出正确写法
  （真机探针确实要跑，可显式传 allowCrashApi）
• 取证：桥每笔请求执行前落盘 %TEMP%\akdagent-lastop-<host>.json（带 session/计数，与心跳互校）
  ⇒ 真被卡住时能指名是哪一笔、参数是什么，不再靠猜
• 恢复：诊断信息与「桥心跳已过期」的报错里直接给三步 ——
  ① 到宿主里关掉那个错误框 → ② Ctrl+S 保存工程 → ③ 脚本菜单重跑桥；悬浮球上也会弹这条

4️⃣ 音区偏移（toneShift）与宿主的取值域对齐

真机确认 ±800 音分是宿主自己的上限（写 900 / 1200 / −1200，宿主都静默夹回 ±800）⇒ 桥现在按 ±800 夹，
并回 clamped: true（比宿主静默夹更透明）；参数量纲守卫会拿单一事实源与桥的实现逐项对账。

下载

• Windows（推荐）：AKDAgent-1.0.2-x64.exe（378.4 MB · 2026-09-27 构建）
  SHA256 = b7294ebffc53552dfd03ef748c8c80f5fb4a0bfbdba83dab0bd7981e873c8fa3
• macOS（Apple Silicon）：AKDAgent-1.0.2-arm64.dmg / .zip（GitHub Actions 同日构建，含上面全部修复）
  dmg SHA256 = f72e905ecc50e9019483dcb73762abf965c0b02368b350cb9f0fbaaa52b4498d
zip SHA256 = 26b988c6bcf347751ac3036dcbb921667b7a10567486d708ca39335ae9ac7bcc

装完请做两件事（否则宿主里跑的还是旧桥）

1. 重新部署桥：设置 → SV 集成 → 一键部署（把新桥写进各宿主的 scripts\Agent\）
2. 在 SV / IX 里重跑一次桥：脚本菜单 → Agent → AKDAgentBridge → Run
   （Lua 桥是常驻脚本，不重跑不会热更）

版本自查：桥应为 1.0.2、侧栏面板 1.0.2-js、客户端「关于」为 1.0.2。
悬浮球/设置页的「桥」提示里也会显示当前宿主里真正在跑的桥版本。

安装

• Windows：覆盖安装即可（向导版安装器，一路下一步）；装完重启客户端
• macOS：拖进「应用程序」后右键 → 打开（未签名 / 未公证包，首次需要这样放行）

如果仍然报错

装完重启后，把下面任一个发我们（都不含 API 密钥）：

1. %APPDATA%\AKDAgent\last-turn-error.json ← 最直接
2. 或 %APPDATA%\AKDAgent\akdagent.log 里带 [akdagent] turn/end reason 与 ⇒ 可能的原因 的那两行
3. 或 %APPDATA%\AKDAgent\mcp-selftest.json

若是「宿主里弹了脚本错误框」这一类：%TEMP%\akdagent-lastop-<host>.json 会告诉我们卡在哪一笔 op。

存量用户（更新前就已经踩过凭据那个 bug 的）

装完重启客户端即自愈，不需要手工步骤：启动时会把你填的 %USERPROFILE%\.dsh\.credentials.yaml
补进/覆盖宿主真正读的 %USERPROFILE%\.dsh-akdagent\.credentials.yaml（哪怕后者里留着一份空的 refs: {}）。
反向也做了保护：源那份不存在时不会去动隔离家目录里已有的凭据。

不想装包（或让还在用 1.0.0/1.0.1 的人立刻可用）：把源那份复制成宿主读的那份，然后完全退出客户端重开：

copy "%USERPROFILE%\.dsh\.credentials.yaml" "%USERPROFILE%\.dsh-akdagent\.credentials.yaml"

AKDAgent 1.0.1（Windows x64 · macOS arm64）

⚠️ 本页已被 v1.0.2 取代：那一版含凭据闪退修复、SV 集成 HTML 护栏（配置向导 / 部署确认）、宿主脚本错误框的三道防线（预检 / 取证 / 恢复三步）与 toneShift 取值域对齐宿主 ±800。Windows 请下 1.0.2；本页资产仅作历史留档。

AKDAgent 1.0.1（Windows x64 · macOS arm64） —— 修一个"新机器上第一句话就失败"的真 bug，外加整套"出错了能查出来"的诊断。

⚠️ 补丁资产：AKDAgent-1.0.1-x64-keyfix.exe（2026-09-26 追加）

1.0.1 的「每次启动补齐凭据」有一个没覆盖的启动分支：如果上一次的内嵌宿主进程还活着
（客户端被强杀 / 卸载残留），客户端会复用它，而那段补齐代码挂在「新起宿主」的路径里
⇒ 被整段跳过 ⇒ 装了 1.0.1 仍然「一发消息就 回合结束（error）」。
手工 copy 凭据之所以能立刻修好，是因为宿主对该文件是热重载，与客户端版本无关。

这一份修两件事：① 凭据/设置的同步移到「无论复用与否都执行」的位置；
② 内嵌宿主记录里记住「是哪个客户端版本起的」，版本不一致就杀掉重起 ⇒ 升级后不再用旧宿主跑旧逻辑。

• 版本号不变（仍是 1.0.1）⇒「关于」页看不出区别；指纹：日志
  %APPDATA%\AKDAgent\akdagent.log 里出现 上一次的内嵌 host 是 v… 起的 或 已同步凭据/设置： 即为本补丁
• 谁该下：装过 1.0.1 仍然报错的人；以及所有 1.0.1 用户（建议换）
• Windows 覆盖安装即可，装完重启客户端（重启后旧宿主会被自动换掉、凭据自动补齐）
• macOS：同一处修复已并入本页 mac 资产（2026-09-26 由 GitHub Actions 重建）
• SHA256 = 696324add8a775d9dcc75f34c955e06769a0416483b289b1d0018137ae6bec2d

修了什么

① 新机器上填了 API Key，却「一发消息就 回合结束（error）」（本次主修）

• 真因：客户端把 key 写进 %USERPROFILE%\.dsh\.credentials.yaml，而内嵌宿主读的是隔离家目录 %USERPROFILE%\.dsh-akdagent\.credentials.yaml；隔离家目录的凭据只在它第一次被创建时抄一次 —— 那一刻用户还没填 key ⇒ 抄了个空，之后再也不抄 ⇒ 宿主永远没有 key ⇒ 每个请求在 HTTP 层被拒（AUTH/401，实测 1.4 秒返回）⇒ 界面上"明明配好了 key"，但每一轮都失败，新建对话也一样。
• 为什么开发机上一直复现不出来：开发机的 ~/.dsh 早就有凭据，首次那一抄抄到了。只有全新机器才中。
• 现在：每次启动都补齐缺失的凭据/设置 ＋ 保存 key 时即时镜像一份进隔离家目录（两道保险）。

② 出错了却看不出来 ⇒ 现在一眼可查

• 每轮失败把真因写进 %APPDATA%\AKDAgent\akdagent.log（[akdagent] turn/end reason = {…} ＋ 一句人话原因），并落 %APPDATA%\AKDAgent\last-turn-error.json
• 人话映射覆盖：401/AUTH（key 无效或不属于当前提供方）· 402（欠费）· 403（无权限）· 429（限流 / 该 key 无此模型权限）· TRANSPORT（网络不通）· REQUEST_EXTENSION（profile 插件条目）· 5xx
• MCP server 注册前自检（initialize + tools/list，6 秒超时）：不过就不注册（宁可少 44 个工具，也不让"注册了却握不上手"拖垮每一轮）；结果落 %APPDATA%\AKDAgent\mcp-selftest.json
• 内嵌 MCP server 的启动横幅默认静音（以前它会被客户端记成 ERROR [dsh:err] …，看着像故障，其实只是我们自己的横幅）

③ 健壮性

• ONNX 改懒加载：缺 ONNX 原生件（最常见原因：没装 Microsoft Visual C++ 运行库）时，不再整颗 MCP server 起不来，只有 sv_extract_notes 一个工具返回明确错误，其余 43 个照常可用
• 桥（1.0.0）与侧栏面板（1.0.0-js）没有改动 ⇒ 不需要重新部署桥，装完重启客户端即可

下载

• Windows（推荐）：AKDAgent-1.0.1-x64-keyfix.exe（378.3 MB · 2026-09-26 补丁，见上方说明）
  SHA256 = 696324add8a775d9dcc75f34c955e06769a0416483b289b1d0018137ae6bec2d
• Windows（原始 1.0.1，含「复用孤儿宿主」这个洞，建议改用上面那份）：AKDAgent-1.0.1-x64.exe
SHA256 = cebbad7f4f35651fd42eed910c2f4efbfafa446023df584114addb2eea159ee8
• macOS（Apple Silicon）：AKDAgent-1.0.1-arm64.dmg / .zip（由 GitHub Actions 构建，见本页附件）

安装

• Windows：覆盖安装即可（向导版安装器，一路下一步）；装完重启客户端
• macOS：拖进「应用程序」后右键 → 打开（未签名 / 未公证包，首次需要这样放行）

如果仍然报错

装完重启后，把下面任一个发我们（都不含 API 密钥）：

1. %APPDATA%\AKDAgent\last-turn-error.json ← 最直接
2. 或 %APPDATA%\AKDAgent\akdagent.log 里带 [akdagent] turn/end reason 与 ⇒ 可能的原因 的那两行
3. 或 %APPDATA%\AKDAgent\mcp-selftest.json

存量用户（更新前就已经踩过这个 bug 的）

装完 1.0.1 重启客户端即自愈，不需要任何手工步骤：启动时会把你填的那份 %USERPROFILE%\.dsh\.credentials.yaml 补进/覆盖宿主真正读的 %USERPROFILE%\.dsh-akdagent\.credentials.yaml（哪怕后者里面已经留着一份空的 refs: {} —— 那是旧版本留下的，会被覆盖掉）。反向也做了保护：如果你 ~/.dsh 那份不存在，不会去动隔离家目录里已有的凭据。

不想装包（或让还在用 1.0.0 的人立刻可用）：把源那份复制成宿主读的那份，然后完全退出客户端重开即可 ——

copy "%USERPROFILE%\.dsh\.credentials.yaml" "%USERPROFILE%\.dsh-akdagent\.credentials.yaml"

AKDAgent 1.0.0（Windows x64 · macOS arm64）

AKDAgent 1.0.0（Windows x64 · macOS arm64） —— 用对话操作 Synthesizer V Studio / Instrument X 的 AI 助手（基于 DSH）。

下载与安装

1. 下载本页的 AKDAgent-1.0.0-x64.exe（378.3 MB）
   • SHA256 = 6b4159b37650a18fb8ea566f50a7215725c0ade8e7e0ac567693c2d4973d4afa
   • 安装包未签名 ⇒ 首次运行 Windows SmartScreen 会拦一下，点「更多信息 → 仍要运行」即可
2. 装好启动后会看到悬浮球；首次会让你填 DeepSeek API Key
3. 设置 → SV 集成 → 对着宿主的 scripts 目录点**「部署桥」+「部署面板」**
   （桥装到所有宿主目录；侧栏面板只装 SV2 / IX —— SV1 没有侧栏机制）
4. 打开宿主（Synthesizer V Studio / Instrument X），在脚本菜单里运行一次 AKDAgentBridge.lua
   （桥必须手动起一次 —— 面板没有文件能力，起不了桥）
5. 之后就能用悬浮球对话，或直接在 SV2 / IX 的侧栏面板里输入、点选项

⚠️ 若你装过更早的 1.0.0 构建：这一版把桥升到 1.0.0 / 面板升到 1.0.0-js，请重新部署 + 在宿主里重跑一次桥才生效。

macOS（Apple Silicon / arm64）：

1. 下载 AKDAgent-1.0.0-arm64.dmg（435.0 MB）或 AKDAgent-1.0.0-arm64.zip（434.2 MB）
   • .dmg SHA256 = d073d613e846a96c50233fec7eacd339150ac93b1bfa5ece26f6b46301afa4be
   • .zip SHA256 = a17f73db6875ed389868c9f93a4dd8aae7de24f0879acdb6486d5f3b584486fc
2. 双击 .dmg → 把 AKDAgent 拖进「应用程序」（zip 版解压后同样拖进去）
3. 首次打开：右键 → 打开（安装包未签名 / 未公证 ⇒ 直接双击会被 Gatekeeper 拦；
   或在「系统设置 → 隐私与安全性」里点「仍要打开」）
4. 启动后菜单栏出现图标、桌面出现悬浮球；后面步骤与上面 Windows 那套一致
   （填密钥 → 设置里「SV 集成」部署桥/面板 → 在宿主里手动跑一次 AKDAgentBridge.lua）

⚠️ 只支持 Apple Silicon（M 系列芯片） —— Intel Mac 不支持（ONNX 运行时不提供 macOS/x86-64 二进制）。
「关于本机」写 芯片 Apple M… 就能用；写 处理器 Intel 就不行。
语音输入首次启用需要授予麦克风权限（未签名包有时会被系统反复询问）。

这一版有什么

• 修「刚启动后第一次开设置窗，输入框有光标但敲键没字」：那是键盘焦点状态不同步（OS 把 key
  事件送去了别的窗口，而设置窗的渲染进程还以为自己活着）。现在：设置窗等页面画好再显示，显示后
  显式给渲染进程焦点并自查两次；悬浮球改用「显示但不抢焦点」（它启动时/用户双击第二次时会
  把自己显示出来，以前那一下会把焦点从你正在打字的窗口抢走）。
• 修 IX 崩溃（重要）：dynamics 在 Instrument X 里是音符级力度包络，不是组级 automation；
  但宿主的 getAutomation("dynamics") 不报错、会返回一个像模像样的"假对象"，在它上面读点/写点会
  毒坏宿主内存、几秒~几十秒后在无关位置崩（一天两次实测：0xc0000409 / 0xc0000005，空工程也能
  复现）。现在：桥的 set_automation 见到 dynamics 直接报错（连 getParameter 都不调），手写脚本里的
  getAutomation/getParameter("dynamics") 也会被静态拦下并给出正确做法（改力度包络走 .ixp 文件路线）。
  读点类 API 在真正的 automation 对象上照常可用。
• 侧栏面板：SV2 与 IX 可以同时连（客户端每台宿主各跑一个中继）
• 悬浮球 IX 皮肤：接上 Instrument X 时换成 IX 蓝主题 + IX logo
• 模型页：预设提供方也能改 Base URL / API 协议 / 模型列表（留空 = 恢复内建默认）
• 应用内帮助页：悬浮球右键 → 帮助
• 修：设置页「看得见但输入框打不进字」（密钥弹窗曾是设置窗的模态子窗 ⇒ 父窗被 Windows 禁用）
• 修：IX 面板一直显示「还没连上悬浮球」
• 离线知识随包（技能包 + 参考文档）；桥/面板版本轴与产品版本对齐（桥 1.0.0 · 面板 1.0.0-js）

环境

• Windows 10+ x64
• Synthesizer V Studio 1.x / 2.x，或 Instrument X 1.0.1+（侧栏面板需要 SV2 / IX；SV1 只能用悬浮球对话）
• macOS（Apple Silicon）这次不发成品包：仓库里备好了 electron/scripts/mac-build-all.sh（两步出包），
  要自行在一台 Apple Silicon Mac 上构建

备注

• 桥与宿主的通道是本地文件通道（%TEMP%\akdagent-*）：不出网、不碰剪贴板、不抢你的焦点
• ⚠️ 在宿主里干活请勤按 Ctrl+S：脚本/桥没有保存工程的能力，而宿主崩溃（例如上面那条已修的
  dynamics 坑）会让未保存内容直接丢掉
• 遇到问题：悬浮球右键 → 帮助；也可以到 B 站 / 邮箱找我（见应用内「关于」页）

构建输入（CI 用，非发行版）

这里放 GitHub Actions 出 macOS 包所需的大件输入，不是给用户下载的发行版。

• akdagent-mac-payload-arm64.zip：Mac 出包整包（含 dist/、dsh-runtime/、node tar.gz 等仓库里装不下的大件）。
  CI 把它当输入，脚本一律取仓库最新版覆盖，所以改了出包脚本不用重打整包，重跑工作流即可。
• 用法见仓库里的 .github/workflows/mac-build.yml。

正式发行版请看 v1.0.0。