AKDAgent 桥协议 v1（文件通道）

📌 传输方式（2026-09-12 起，唯一通道）：剪贴板已整体退役，只有文件通道 —— 请求 <dir>\akdagent-req-<host>.json（客户端原子替换写入：写 .tmp 再 rename）· 响应 akdagent-res-<host>.json（桥写 .tmp 再改名，失败则先删再改）· 心跳 akdagent-hb-<host>.json（存活 + 宿主信息 + ops 能力清单 + 实际 dir）· 启动结果 akdagent-boot-<host>.json（成功/致命错误，供外部排障）。 <dir> 解析顺序（两端同序）：① %USERPROFILE%\AKDAgent\ipc（存在且可写才用 —— Lua 不能 mkdir）② os.tmpdir()（= %TEMP%）。 ⚠️ 客户端另有环境变量 AKDAGENT_IPC_DIR 可覆盖，桥不读它 ⇒ 设了就必须让桥也落在同一目录。"两端 dir 不一致"是这套通道最常见的故障（心跳里会写实际 dir，先对一眼）。 桥只有 Lua 一种 ⇒ run_script 执行的是 Lua（冒号调用、索引 1 起），不再是 JS。 本文件后文凡提到 SVCMD:/SVRES:/剪贴板的，均只作历史参考；现役事实以 sv/lua/AKDAgentBridge.lua（现 1.0.0）与 server/src/fileipc.ts 为准。

通信双方：Bridge（宿主内常驻 Lua 脚本，执行方）与 Client（MCP server / Electron 客户端，请求方）。 另有旁路产物 akdagent-log-<host>.txt（桥的运行日志）与 akdagent-diag-*（诊断），排障时先看它们。

规范原文维护在 knowledge/docs/PROTOCOL.md（与本技能同源，改协议要一起改）；通道客户端实现 server/src/fileipc.ts · 桥侧 sv/lua/AKDAgentBridge.lua。

🔢 索引基准（全仓总纲 —— 看到任何 index 先读这条）

三条最容易踩的坑

1. get_selected_notes 返回的 index 是「本次选中结果数组内的序号」（0 起），不是「组内下标」。 要写 write_pit 的 indices（那是组内下标）必须另取 Note#getIndexInParent —— 而且 Lua 侧要 +1 换算。
2. 序号类参数的基准逐个确认：trackIndex / audioTrackIndex 0 起；part 1 起（tools.ts 里 part - 1 即证）；不要想当然。
3. 别用"试一下"确定基准：Lua 绑定的错误穿透 pcall（直接弹脚本错误框），一次试探就打断用户 —— 已实测两次，故 Lua 桥里不做任何探测，基准写死 CFG.INDEX_BASE。

消息格式（文件通道）

请求 <dir>\akdagent-req-<host>.json（单行 JSON，客户端原子替换写入）：

{ "v": 1, "seq": 1789175384220009, "id": "fileipc-1789175384220009",
  "op": "get_selected_notes", "args": {} }

响应 <dir>\akdagent-res-<host>.json（桥写 .tmp 后改名）：

{ "v": 1, "id": "fileipc-1789175384220009", "seq": 1789175384220009, "ok": true,
  "ts": 1789175384, "host": "sv", "result": { … } }
{ "v": 1, "id": "…", "seq": …, "ok": false, "ts": …, "host": "sv", "error": "…" }

🔑 id 按字符串比较，别比 seq（server/src/fileipc.ts 实测教训）：Lua 曾把 16 位 seq 编成科学计数法（1789175384220009 → 1.78917538422e+15）丢精度 ⇒ 客户端只按 id 判等，数字比较只当冗余条件 —— 否则会把"对端数字序列化不精确"放大成"桥不响应"。 🔑 宿主标识写在文件名里：-sv（Synthesizer V，SV1/SV2 共用）/ -ix（Instrument X）⇒ 旧文档说的"SV1 与 SV2 互相抢答"在文件通道下不复存在（各读各的文件）；但同一宿主开两个实例仍会互抢同一份文件名。

规则

1. 心跳声明能力（canServe）：发之前先看 akdagent-hb-<host>.json —— ① 有心跳文件 ② ts 新鲜（≤ 15s）③ 该 op 在心跳的 ops 数组里被明确声明。三条都过才发；否则明确报"无心跳 / 心跳过期 Ns / 桥未声明 op 'x'（并附 advertisedOps）"。桥自报能力是最可靠的判据（旧的文件/剪贴板白名单已随剪贴板一起删除）。
2. id 去重（主键是 id，不是 seq）：桥内存里存 done[id]；重复 id ⇒ 不重复执行，直接重发缓存响应（客户端超时重试正是靠这条）。缓存被淘汰后再来同 id ⇒ 回 ok:false, error:"duplicate request id (response evicted from cache)"。 ⚠️ 别用 seq > lastSeq 去重 —— 不同客户端的 seq 尺度可差 1000 倍，先到的大 seq 会把后到的小 seq 请求永久静默忽略（实测 reqSeen 卡住、心跳正常、只有 resend 日志）。桥里 lastSeq 仅作统计。
3. 应答后必须消费请求文件（consumeReq）：桥应答（或重发缓存）后删掉 req 文件 —— 且只在"文件内容仍等于读到的快照"时删（客户端是原子 rename 写入，避免误删新请求）。不消费的后果实测过：每拍重读同一请求 ⇒ 命中缓存 ⇒ 每拍重发响应（日志每秒 2~3 条 resent cached response、持续 90 秒，而客户端其实只发了一次）。
4. 同一时刻只允许一个在途请求：客户端必须串行化（server 侧已做互斥）⇒ 模型侧不要并发下发，串行是设计不是卡。
5. 超时：客户端默认 10s、轮询 40ms；桥侧轮询间隔 300ms（POLL_MS）。 ⚠️ 超时是"模糊"的 —— 它只代表"我们不等了"，宿主可能仍在把那次写做完 ⇒ 别急着重试写，先 ping / 重读目标确认状态；确要重试就用同一个 id（命中缓存会重发响应，不会重复执行）。
6. 执行方语义：所有写操作执行前先 newUndoRecord()（run_script 缺则拒绝，readonly:true 跳过），保证宿主内可撤销。 📌 它是一个撤销恢复边界，不是自动回滚（见下「指纹 / 守卫」§ 的事务语义）。

操作清单（v1 · 共 32 个 op，以实现为准）

真源 = sv/lua/AKDAgentBridge.lua 的 OPS.*；2026-09-19 逐条核对过。 心跳的 ops 数组就是这张表（桥自报），canServe 拿它判"这个 op 现在能不能服务"。 关系：32 个 op ↔ 53 个 MCP 工具（其中 44 个是 SV/IX 工具，另 3 个是 ACE Studio 工具，见下条） —— 工具比 op 多，因为分离 / 音频分析 / 旋律生成 / 织体渲染等完全在本地算，不经桥。

读操作（13）

写操作（16）

维护（1）

📌 MCP 工具面（53 个）见 knowledge/docs/MCP工具清单.md；本表只讲通道 op，两者不是一一对应。 ⚠️ 其中 3 个是 ACE Studio 工具（ace_state / ace_cli / acep）—— 它们不走本协议（ACE 是第三方宿主，没有心跳文件、没有 op）。

⚠️ 写操作护栏

📌 现状下的正确姿势：写完必须重读（get_layout / get_melody_notes / get_selected_notes）才算数，没重读就别对用户说"已经改好了"。

指纹 / 守卫 / 体量护栏（规格，2026-09-11 定）

起因：写操作目前只有"id 防重 + 参数类型校验 + 写前 undo"。 而 transpose_selected_notes / set_selected_lyrics / fill_track_lyrics / sv_import_musicxml（工具侧） 都是按位置批量写 —— 用户手动改一笔，模型手里的旧计划就会错位。 这层规格参照上游 synthv-agent 的"指纹 + guardToken + 重读不猜"做法（摘要改写，不逐字照抄）。

1. 指纹（fingerprint）：读操作产出，写操作必带

读操作（get_selected_notes / get_current_group）额外返回：

{
  "guard": "g-8f3a2b1c",          // 短 opaque token，代表"这份读回结果"
  "fingerprint": "…12位hex…",      // 规范化内容的短哈希
  "scope": "selection",            // selection | group
  "count": 8,                      // 参与指纹的音符数
  "groupUuid": "…"                 // 组身份
}

指纹字段（每个音符取这些，按 index 排序后规范化再哈希）： pitch · onsetQuarter · durationQuarter · endQuarter · lyrics （扩展位：phonemes · attributes · pitchAutoMode —— 需要更严时开启）

2. 写操作带上"我读到的是什么"

{ "op": "transpose_selected_notes",
  "args": { "semitones": -12, "expect": { "guard": "g-8f3a2b1c" } } }

桥端写前重算指纹并比对：

3. 分级落地（避免一次性破坏现有调用）

切换条件：warn 跑一段没有误报 → 再按工具逐个切 strict（先切破坏性最强的：转调 / 填词 / 导入）。

4. 结果体量护栏（上行方向）

响应超过 maxChars（默认 20000）时不返回全量，而是：

{ "ok": true, "truncated": true, "total": 379, "returned": 40,
  "hint": "用 groupIndex/索引区间分批读，或加 fields 收窄字段",
  "sample": [ … ] }

⇒ 带收窄指引地失败，而不是把上下文淹掉。（已有下行载荷坑的记载，这是上行的对称护栏。）

5. 事务语义（澄清）

newUndoRecord() ＝ 一个撤销恢复边界，不是自动回滚。 若桥返回 undoRequired:true（写中途失败、状态不明），正确做法是让用户在 SV 里按 Undo，然后重读、重算计划、再重试。

6. 共享组写保护（待实现）

NoteGroup 的内容对所有 reference 都只有一份 ⇒ referenceCount > 1 时： 内容写默认拒绝；只有显式声明allowAllReferences:true、且给出吻合的expectedReferenceCount时才放行。 （offset、mute 这类reference-local字段不在此列。）

7. 排障与语义对照（照抄形态、不照抄内容）

时序示例（文件通道）

Client（MCP / Electron）                          Bridge（宿主内常驻 Lua，轮询 300ms）
  │ ① 读 akdagent-hb-sv.json：心跳新鲜？ops 里有这个 op？   ← canServe() 判据
  │ ② 删掉旧的 akdagent-res-sv.json（防止读到上一轮的响应）
  │ ③ 原子写 akdagent-req-sv.json {v,seq,id:"fileipc-<seq>",op,args}
  │ 轮询 res（40ms/次，超时 10s）                        ──▶  读到 req → 解析
  │                                                         id 已在 done[]？→ 重发缓存响应 + consumeReq
  │                                                         否则 newUndoRecord() → dispatch(op,args)
  │ ◀───────────────────────────────────────────────────  写 res（.tmp → rename）
  │ res.id === 我发的 id ⇒ 命中（**按字符串比 id，不比 seq**）→ 返回给模型
  │                                                         consumeReq(快照)：内容没变才删 req

读的时候顺手能拿到的排障三件套（客户端超时错误里会带上；fileipc.collectDiagnostics）：

dir=<实际目录>            ← 两端目录不一致是头号故障
host=sv
heartbeatAge=11028s      ← 桥可能早就停了（>15s 即判不新鲜）
boot={"bridge":"1.0.0","hostVersion":"2.2.1","indexBase":1,…}
log尾部=…（akdagent-log-<host>.txt 最后 6 行）   ← boot 之外的运行期线索

边界情况处理

• 两端目录不一致（头号故障）：客户端在 %USERPROFILE%\AKDAgent\ipc 有可写目录、桥却在 %TEMP%（或反之）⇒ 请求文件写了但桥永远读不到，表现为"一直超时、心跳却看不到"。先比心跳里的 dir —— 心跳文件在哪个目录，桥就在哪个目录。
• 桥未运行 / 宿主没开：无心跳文件 ⇒ 客户端直接给"无心跳文件（桥未运行）"，不会白等 10 秒。
• 心跳过期（>15s）：判"桥可能已停"，但别据此断言宿主状态 —— 宿主只是把脚本停了/关窗口了都可能；boot 文件里有启动信息，akdagent-log-<host>.txt 有运行日志。
• 重复响应：客户端发请求前先删旧 res 文件；桥应答后消费 req 文件（内容没变才删）⇒ 旧的"每拍重发响应"问题已消除（见「规则 2、3」）。
• 同一宿主开两个实例：会互抢同一份 akdagent-*-sv.json（文件名里只有宿主，没有实例号）⇒ 同宿主只开一个。
• SV1 与 SV2 同开：文件通道下不再互相抢答（各自读自己的 -sv 文件）；但两者都会在同名文件上应答，所以"同宿主单实例"这条纪律仍然适用。
• 不许探测：Lua 绑定的错误穿透 pcall（直接弹脚本错误框）⇒ 桥内不做任何探测（见「索引基准」第 3 条），模型侧也别拿"试一下"当查询手段。

载荷过大的坑（形态已变）：剪贴板时代经 base64 + powershell -EncodedCommand 走命令行，有 ~32KB 上限； 现在载荷走文件 ⇒ 命令行上限不再是瓶颈，但请求/响应仍不宜塞上千个展开后的音符（桥端要 JSON 解析 + 逐音符建对象，且响应体量护栏还没实现）。 对策不变：把"展开/生成"放到桥端做，只传短指令（如和弦序列而非展开音符、模板而非成品织体）。 详见 ../sv-scripting/examples/载荷过大-ENAMETOOLONG.md（历史实测数据仍可参考）。

能力边界：对用户怎么说（别误报）

📌 来源：上游 synthv-agent/SKILL.md（摘要改写）。

桥会话与缓存的重置（宿主重启 / 桥重跑）

📌 来源：上游 synthv-agent/SKILL.md（摘要改写；对应上游的会话变更错误码）。

• 桥是宿主内的常驻脚本：宿主一重启桥就没了；桥源文件改了也必须在宿主里重新运行一次才生效（当前会话跑的是加载时的旧版）。
• 桥重跑 ⇒ id 防重表与响应缓存归零（都在桥内存里，ST.done 有上限、超限按插入序淘汰）⇒ 同一个 id 再发一次不算重复，那一次会真的执行。宿主重启后想"重发"旧请求之前，先确认目标的实际状态。
• 判断"还是不是同一个桥会话"：看 ping / 心跳（akdagent-hb-<host>.json）里的 bridge 版本、dir、ops 清单、pollTicks 是否连续 —— 别靠记忆。
• 客户端侧同理：MCP 侧改了 tools.ts 必须重编译并重启 MCP 进程，否则工具面与实现对不上。

不抢用户焦点 / 不动用户状态（一等约束）

📌 来源：上游 synthv-agent/SKILL.md（摘要改写："无焦点操作"是其硬要求）。 ⚠️ 上游那条能力来自注入层（无焦点点击），而已裁定不做注入 ⇒ 这里只保留对我们成立的部分。

• 用户的选区、当前编辑组、播放头、视图滚动位置是共享状态，而且是我们好几个工具的输入（get_selected_notes、apply_lyrics 的填词范围、write_pit 省略 indices 时的默认目标都读它）⇒ 除用户明确要求（播放 / 定位 / 选中）之外，不要为了自己方便去改选中、切组、滚视图。
• 读操作必须零副作用：读一次不该让用户的选中没了。
• 报错也是打扰：Lua 绑定的错误穿透 pcall（直接弹脚本错误框）⇒ 桥里不做探测（见「索引基准」第 3 条），模型侧同理 —— 别拿"试一下"当查询手段。
• UI 类动作要回报宿主执行后的实际状态，不能把请求值原样当结果（目前只有 playback，返回 {status}）。
• ⛔ 语言（语种）也属于用户状态 —— 默认不动（这是 AKDAgent 的整体纪律，不限说唱 / 不限作词）： 语言链 = 音符属性 > 音符组属性 > 轨道属性 > 声库语言（都没有 ⇒ 取声库录制语言）；用户比我们清楚声库语种 ⇒ 不主动改音符 / 组 / 轨语言，只有用户主动反馈"多语言混杂"时才按词内语言自动设。 ⚠️ 另有一条技术后果：语种与声库不兼容 ⇒ 无音素 ⇒ 该组不渲染（实测：英文声库 + 中文词 ⇒ 计算类接口全 null） ⇒ 读到全空时先查这条，别先怪"渲染没完成"。正本见 skills/akdagent-playbook/SKILL.md 的 0.6b 节（AKDAgent 整体语言纪律）。

轨克隆与非主 Vocal 组（规格，暂无对应 op）

📌 来源：上游 synthv-agent/SKILL.md（摘要改写）。 op 表里没有 clone_track；但 run_script 里手写 Track#clone()（references/06-track-misc.md 的 splitTrackAtPlayhead 正是这么做的）会撞上同一个问题。

• 整轨克隆时，轨上若挂着非主 vocal 的组：把内容变独立了，不等于保住了那些组原本的 Vocal 身份 —— 官方 API 没有读回或核实身份的接口 ⇒ 必须请用户人工复核（看组上挂着谁 / 听），别替它打包票。
• 绝不声称 API 能读出或命名那个 Vocal（连"当前歌手是谁"都读不到，见 sv-scripting 的不可做清单）。
• 想要的是一条空壳轨、而它沿用主 Vocal 那套上下文时，别去克隆整轨：走建新组 + 挂 reference更干净（ create_harmony_group / write_chords 就是这个做法）。
• 顺带：NoteGroup 的内容是跨 reference 共享的（见上文「共享组写保护」）—— 克隆出的轨与原轨指向同一份内容时，改一处会同时变两处。

详见

• knowledge/docs/PROTOCOL.md —— 协议规范原文（与本技能同源，改协议两处一起改）
• server/src/fileipc.ts —— 客户端实现（目录解析 / canServe / 原子写 / 按 id 匹配 / 超时与诊断）
• sv/lua/AKDAgentBridge.lua —— 桥侧实现（OPS.* 32 个 op · pollOnce / consumeReq / done[] 去重 · 心跳字段）
• skills/sv-project-format/SKILL.md —— .svp / .ixp 工程文件格式与宿主差异（音符/组/自动化怎么写）
• 📦 原先的 references/svp-format.md 已删除：.svp 工程结构 / 版本策略 / 音频轨注入 / 196 模板 → skills/sv-project-format/SKILL.md；声库 nofs/vocoder/中文名 → skills/sv-scripting/references/10-声库与声线.md §5