# 從空白 Timeline 到一首完成的 VOCALOID 歌曲

## 把作曲、調教、渲染、混音、Mastering 與可驗證交付，做成 Agent-Native 的 VOCALOID3 MCP

- **專案 checkpoint：** 2026-07-18；matching VSQX delivery 於 2026-07-19 補齊
- **實作：** TypeScript、Model Context Protocol、native Win32 helpers、VOCALOID3 Editor、FluidSynth、FFmpeg
- **主要已驗證聲庫：** IA_ROCKS
- **本文描述的基線：** local commit `91545a0`，並包含後續 paired-delivery convention
- **當時自動驗證：** 47 tests discovered，45 passed，2 intentional skips，0 failed
- **English edition：** [From a Blank Timeline to a Finished VOCALOID Song](from-blank-timeline-to-finished-vocaloid-song.en.md)

---

## 摘要

這個專案起源於一個看似很簡單的念頭：把 VOCALOID 暴露成 MCP server，讓 coding agent 幫忙做一首 Vocaloid 歌。

真正麻煩的字是：**歌**。

一個成功的系統不能停在輸出 Standard MIDI File、丟出幾顆 note、轉換一份既有 VSQX，或讓 Editor 唸幾個孤立音節。我們真正想要的體驗比較像這樣：

> 給 agent 一份創作 brief、歌詞，甚至一條完全空白的 timeline。讓它設計 form、melody、harmony、rhythm、phoneme、vocal expression、accompaniment、tempo／meter 變化、mix intent 與 delivery target。接著由同一個 agent 產生原生 VOCALOID project，透過 original Editor 和合法聲庫渲染人聲，組裝 stems、mastering、分析性聆聽、局部修改，最後交付一份有 provenance、可驗證的 stereo WAV。

這個要求把「寫一點 XML」變成一套小型 production system。它要求我們：

- reverse engineer 足夠多的 32-bit legacy Windows application，才能安全自動化；
- 理解 Yamaha VSQ3／VSQ4 data model；
- 建立適合長時間 agent session 的 canonical song representation；
- 把 creative intent 與 derived artifacts 分開；
- 建立 deterministic accompaniment 與 audio-processing backends；
- 最重要的是，把 interaction cost 壓到 fresh agent 不必每次重新發現 schema。

本文重建了從第一個 native probe，到三套完整 IA_ROCKS delivery pair 的工程路徑。Dead end、crash、錯誤假設、interface redesign、品質失敗與 test evidence 都會保留。同時，它也嚴格區分：什麼真的被證明了，什麼仍需要更好的樂器、更廣的 voice coverage、人耳判斷或下一階段 protocol。

這不是在聲稱軟體已經解決音樂品味。它記錄的是：我們做出了一件可審計的樂器，讓 agent 可以在其中行使音樂判斷。

---

## 目錄

1. [真正的問題：完整製作，不是 MIDI generation](#1-真正的問題完整製作不是-midi-generation)
2. [限制與 definition of done](#2-限制與-definition-of-done)
3. [最終系統總覽](#3-最終系統總覽)
4. [Phase I：考古、schema 與 native reverse engineering](#4-phase-i考古schema-與-native-reverse-engineering)
5. [Phase II：從零產生 native VSQX](#5-phase-ii從零產生-native-vsqx)
6. [Phase III：安全自動化 original VOCALOID3 Editor](#6-phase-iii安全自動化-original-vocaloid3-editor)
7. [Phase IV：從 vocal snippet 到 structured song](#7-phase-iv從-vocal-snippet-到-structured-song)
8. [Phase V：長曲、快速歌詞、配器與 mastering](#8-phase-v長曲快速歌詞配器與-mastering)
9. [Phase VI：canonical song manifest](#9-phase-vicanonical-song-manifest)
10. [Phase VII：日文歌詞與可檢查 tuning gesture](#10-phase-vii日文歌詞與可檢查-tuning-gesture)
11. [Phase VIII：stems、score/render 分析與可重現混音](#11-phase-viiistemsscorerender-分析與可重現混音)
12. [Phase IX：preflight、host readiness、history 與 delivery](#12-phase-ixpreflighthost-readinesshistory-與-delivery)
13. [Phase X：為 agent 重設計 MCP](#13-phase-x為-agent-重設計-mcp)
14. [完整 production workflow](#14-完整-production-workflow)
15. [獨立 agent evaluations](#15-獨立-agent-evaluations)
16. [三種完整 style closure](#16-三種完整-style-closure)
17. [Failure ledger](#17-failure-ledger)
18. [測試與證據策略](#18-測試與證據策略)
19. [Chronological checkpoints](#19-chronological-checkpoints)
20. [Repository map 與 reproducibility](#20-repository-map-與-reproducibility)
21. [安全、provenance 與操作邊界](#21-安全provenance-與操作邊界)
22. [已證明、未證明、下一步](#22-已證明未證明下一步)
23. [可泛化的工程教訓](#23-可泛化的工程教訓)
24. [附錄：production tools 與 resources](#24-附錄production-tools-與-resources)

---

## 1. 真正的問題：完整製作，不是 MIDI generation

很多「AI music」整合把 MIDI 當成邊界。這很合理：MIDI note 容易生成、驗證，也容易送進樂器。但一段 Vocaloid performance 含有普通 MIDI 無法忠實表達的資訊：

- lyric 與 language-specific phoneme；
- singer identity 與 voicebank component binding；
- 作為 consonant timing、而非常規 loudness 的 note velocity；
- accent、decay、opening、bend depth／length、portamento flags；
- vibrato type、onset、depth envelope、rate envelope；
- 隨時間變化的 DYN、BRE、BRI、CLE、GEN、POR、PIT、PBS；
- musical part、pre-measure、mixer 與 singer events；
- licensed synthesis 與 project compatibility 等原生 Editor 行為。

只輸出 MIDI 的 agent 可以提出 melody，卻不能聲稱自己建立了真正的人聲 performance。同樣地，只生成 VSQX、卻從未讓 target Editor 打開的系統，只證明自己的 XML parser 滿意，沒有證明 VOCALOID 接受、渲染或保留它。

因此我們採用一個更強的定義：

> 只有當 agent 能在沒有 input VSQX 的情況下起步，把音樂與 production intent 保存於可檢查的 canonical model，compile 原生 artifacts，透過 original Editor 渲染指定合法聲庫，製作 accompaniment 與 isolated stems，依明確 target mastering，執行獨立 delivery checks，並保留足以重現或修改的 provenance，MCP 才算完成。

這個定義改變了所有 architecture decision。VSQX 成為 derived format，而不是唯一 database；audio analysis 進入 workflow，而不是事後補充；tool design 必須同時考慮 capability、context cost、retry cost 與 mutation safety；一首長曲要能承受數十次呼叫，而不是每次都讓 agent 重送幾千顆 events。

### 1.1 Agent-assisted 不等於把 agent 藏起來

Agent 仍然負責藝術選擇：form、section energy、melodic contour、tessitura、chord tension、rapid syllabic writing、breath、rest、melisma、harmony entrance、tempo change、stereo placement、effect intent，以及判斷 warning 是 bug 還是風格決定。

MCP 提供 affordance 與 guardrail。它不會在單一 `make_song` 按鈕後面偷偷做一首通用歌曲，也不會把所有特殊段落自動修成平淡安全。Analyzer 回報可觀察的風險，不用數字 threshold 取代 taste。

### 1.2 為什麼「from zero」很重要

我們完全可以拿一份 known-good VSQX，替換 note，再稱之為 generation；但我們明確拒絕這條捷徑。最早的獨立 Codex proof 在沒有讀取或複製既有歌曲的情況下，建立一份八小節、41 顆原創 note、62 個 control points 的 project。之後 Yamaha native loader 從中列舉出 351 個 objects。

既有 projects 只作為 format 或 behavior oracle，用於比較 native structure、object tree 與 Editor behavior；它們從未成為最終作品背後的隱藏旋律模板。

## 2. 限制與 definition of done

### 2.1 Legacy application boundary

VOCALOID3 Editor 與它的 libraries 是 32-bit Windows software；大部分 orchestration 和 MCP 實作則在 Linux／WSL 的 Node.js 上執行。Native validation 與 rendering 必須跨越 OS 與 architecture：

```text
Codex / MCP client
        |
        | JSON-RPC over stdio
        v
Node.js TypeScript MCP server in WSL/Linux
        |
        | validated Windows paths + bounded subprocess protocol
        v
32-bit native Windows helpers
        |
        +--> Yamaha Vsq3.dll loader/probe
        |
        +--> original VOCALOID3 Editor UI and licensed synthesis
```

這也是 repository 同時出現 TypeScript、C 與 PowerShell 的原因。假裝 Editor 是普通 HTTP service，只會把最難的 reliability 問題藏起來。

### 2.2 Original Editor 是 synthesis authority

找到 VVD metadata，不代表 singer 已註冊、有 license，或能被目前 Editor 使用。只有真實 render 能證明 availability。Production workflow 中，original VOCALOID3 Editor—not a reimplementation—才是聲音合成 authority。

這也劃出 licensing boundary：reverse engineering 用於理解 file loading 與合法安裝行為，不 patch activation、不繞過 registration、不散布 voice data，也不假裝能取代 licensed engine。

### 2.3 Local、single-user MCP transport

目前 MCP 使用 `stdio`，適合作為 local desktop bridge。它避免把 legacy Editor 與 filesystem path 暴露到 network。若未來要 remote service，需要 authentication、tenant isolation、secret management 與完全不同的 threat model；目前設計不暗示已具備這些能力。

### 2.4 一個被完整驗證的 production voice

最終 style evaluations 使用 IA_ROCKS exact component ID：

```text
BDREB7P2KTWKYDC5
```

另一個本地 ID `BLRGDDR4M3WM2LC6` 是 IA，不是 IA_ROCKS。曾經混淆一次，就足以證明我們需要單一 canonical constant 與 active voice-readiness probe。Architecture 支援其他 voice，但本文 checkpoint 的完整 end-to-end evidence 僅屬於 IA_ROCKS。

### 2.5 Completion matrix

| Layer | 必要證據 |
| --- | --- |
| Composition | 可以從 empty manifest 建立新歌，不需要 source VSQX。 |
| Lyrics | original text、kana reading、normalized reading、mora alignment、locked phoneme 可區分。 |
| Vocal expression | high-level intent 能 compile 成可檢查的 note style、vibrato 與 control curves。 |
| Structure | 支援多 sections、tracks、parts、tempo、meter 與 reusable patterns。 |
| Native compatibility | XSD 與 Yamaha `Vsq3.dll` 都接受生成的 VSQX。 |
| Voice synthesis | Original Editor 用指定 singer 渲染 non-silent audio，不能 substitution。 |
| Accompaniment | 多樂器與 drums 能渲染成 verified stereo audio。 |
| Iteration | stable IDs 與 bounded edits 能修改局部，不必重送整首歌。 |
| Stems | Vocal／instrument 可分軌渲染，pan/dry 與 provenance 明確。 |
| Mix | ordered effects 與 section dynamics deterministic，並保存為 intent。 |
| Master | LUFS、LRA、true peak、clipping、balance 獨立量測。 |
| Delivery | 最終 WAV 只有在 dependency 與 hashes current 時通過，並發布同 basename VSQX。 |
| Recovery | 失敗 render 不產生假 artifact，先前成功工作可以 resume。 |
| Agent usability | 預設 tool catalog compact、typed、有 docs 與 on-demand resources。 |

## 3. 最終系統總覽

成熟系統可以視為五個平面：

```text
                         CREATIVE / CONTROL PLANE

             Agent brief, lyrics, revisions, listening notes
                                |
                                v
                 production MCP profile + resources
             typed outputs | dry-run | preflight
                                |
                                v
                       canonical *.song.json
      timeline | form | harmony | vocals | arrangement | mix | review
                                |
               +----------------+----------------+
               |                                 |
               v                                 v
       NATIVE VOCAL PLANE                 INSTRUMENT PLANE
       VSQ3/VSQ4 compiler                 patterns/placements
       XSD + native loader                FluidSynth + SF2
       VOCALOID3 Editor                   per-track stems
               |                                 |
               +----------------+----------------+
                                v
                         AUDIO PRODUCTION PLANE
                   alignment -> effects -> automation
                   stem sum -> bus -> analysis -> master
                                |
                                v
                         EVIDENCE / DELIVERY PLANE
               hashes | dependencies | history | reviews | QC
```

### 3.1 Implementation layers

| Layer | 代表 modules | 責任 |
| --- | --- | --- |
| MCP routing | `src/index.ts`、`agent-examples.ts`、`style-palettes.ts` | profiles、schema、resources、high-level routing |
| Canonical state | `song-manifest.ts`、`manifest-history.ts`、`mutation-preview.ts` | IDs、hashes、revision、backup、dry-run、artifact graph |
| Musical compilation | `vsqx.ts`、`vocal-phrase.ts`、`japanese.ts`、`harmony.ts`、`tempo.ts` | native structures、lyrics、phonemes、gesture、harmony/groove guardrails |
| Rendering | `render.ts`、`voice-readiness.ts`、`accompaniment.ts`、`stems.ts` | Editor export、voice probe、FluidSynth、isolated stems |
| Audio production | `stem-mix.ts`、`audio-quality.ts`、`audio-review.ts`、`delivery.ts` | effects、automation、analysis、A/B、mastering、delivery |
| Native boundary | `native/vsq_probe.c`、`native/vocaloid_export.c` | 32-bit loader inspection 與 Win32 automation |
| Verification | `tests/`、`notes/`、local `artifacts/evals/` | unit、integration、protocol、routing、full-song evidence |

### 3.2 為什麼 canonical manifest 必須在中心

VSQX 適合作為 Editor interchange format，卻不適合當 agent production system 的唯一 source of truth。它不自然保存 renderer choices、mix chains、artifact hashes、review notes、dependencies 與 mutation history。

因此 `.song.json` 保存 creative/production intent；VSQX、backing、stems、mix、analysis、mastered WAV 都是 derived artifacts。這個區分是 reproducibility 與誠實 staleness detection 的基礎。

## 4. Phase I：考古、schema 與 native reverse engineering

### 4.1 從文件與 schema 開始，不靠猜

本地 VOCALOID3 安裝提供三個互補 truth sources：

1. Editor manual，特別是 phoneme 與 expression semantics；
2. bundled VSQ3／VSQ4 XML schemas；
3. Editor-produced projects 與 native loader behavior。

XSD 檢查 shape 與 bounds；manual 解釋日文 phoneme 與 note property；native loading 暴露 schema 無法表達的 compatibility 要求。三者共同避免系統被單一 sample 的偶然細節綁死。

### 4.2 Binary address 一定要綁 fingerprint

| Binary | Architecture | SHA-256 |
| --- | --- | --- |
| `DSCL3.dll` | PE32 / Intel 80386 | `9bcdc8b8424849f18975af47ceaad984222239ddad57d1554e75b2478fb5f789` |
| `DSE3.dll` | PE32 / Intel 80386 | `f251e7105eee2c8ceb8e632bf22ff50655cb7b87b7e892b6116b3b17c6a4ee5f` |
| `Vsq3.dll` | PE32 / Intel 80386 | `236b4be5c09d17f77e5f9c9a7455817edba01664e760908635157eef2dce7256` |

Proprietary DLL 裡的 address 不是 API，不能假設跨版本穩定。Native helper 動態 resolve decorated exports；reverse-engineered address 只記錄 pinned build，絕不是 universal entry point。

### 4.3 找回 native object tree

第一個真正有用的 bridge 不是 synthesizer，而是 validator。

`native/vsq_probe.c` 透過 Yamaha `Vsq3.dll` 載入 VSQX、初始化 `CVSVsqManagerIF`、呼叫 `fileLoadVsqFile`，再走訪 object hierarchy。這要求理解 VC9 `std::wstring`、interface offsets、generic `IVSVsqObject`、pointer-vector layout 與 primary vtable identities。

Probe 在兩份差異極大的 projects 上驗證：一份真實 V4 corpus project 有 20,402 objects、6 tracks、6 parts；早期 smoke project 有 83 objects、1 track、1 part。這比單純 XML parse 強得多。

### 4.4 Native validation 修正了我們自己的錯誤直覺

一次 load failure 被錯怪到 phoneme `4 a`，彷彿 `4` 是 count 或非法 token。Manual 與 `KanaNote.lua` 卻證明 `4` 正是日文 ら 行的官方 flap/tap phoneme。

真正問題在別處：phoneme element 要保存 raw symbol、每顆 note 要有標準 note-style/vibrato fields、string elements 要符合 Editor 的 CDATA 行為。修正後，一份包含 `4 a`、note styles、vibrato sequence 與 DYN 的 project 被 native loader 接受為 77 objects。

這形成一條規則：**validator 應報告 observed facts，不能替我們的直覺背書。**

### 4.5 Direct DSCL／DSE synthesis 的迷人死路

IDA 顯示一條可能的 native path：

```text
VSQX
  -> CVSVsqManagerIF / IVSMusicalPart
  -> sequence time map
  -> CxDaisyMidiFile::EncodeMusicalPart
  -> CDaisyMidiBuffer
  -> CRtSynthesis::OpenSynthesizer
  -> DSE3 step synthesis
  -> CWaveFile
```

Recovered contracts 包括 API version `20008017.0`、engine token `20012012.0`、256-sample frame，以及 `EncodeMusicalPart` 對 musical part 和 time map 的需求。Probe 已走到 load VSQX、select part、create map、encode Daisy、load DSCL3/DSE3、resolve exports。

真正 synthesis 停在：

```text
DSESetDBMPath result=-100
DoSynthesis failed
render_status=71
```

Decompilation 顯示參數不是普通 voice directory，而涉及 `SOFTWARE\VCLDASGN3\%s` 與 32-bit registry 下的 `DATABASE\VOICE2`／`VOICE3` registration state。

正確決定是停止把 direct DSE 當 production path。我們不 patch activation、不模擬 undocumented voice table。Original Editor 本來就擁有合法合成 context，因此 automation 向上移到 application boundary。

### 4.6 Dead end 仍然是 deliverable

這段調查留下 Yamaha-loader compatibility test、binary fingerprint/ABI boundaries、native synthesis 保留 VOCALOID expression 的證據、licensing/registration boundary，以及採用 Editor automation 的可解釋理由。

Systems work 裡，一條被完整描述、然後有紀律放棄的路，本身就是成果。它防止下一個 maintainer 重複同一個危險實驗。

## 5. Phase II：從零產生 native VSQX

### 5.1 Timing model

Writer 使用 VOCALOID 的 480 ticks per quarter note。High-level position 是 zero-based：

```text
measure, beat, tick
```

它們透過 tempo/meter map 轉換。Part-local editing 與 song-global placement 必須分開，否則很容易被 pre-measure 或 part offset 整段平移。

Structured writer 支援 VSQ3／VSQ4、最多 16 vocal tracks、多 parts、tempo/meter changes、mixer、mono/stereo WAV audio parts，以及 note styles、vibrato、master curves。

### 5.2 Native note content

一顆 note 不只是 pitch、onset、duration。Writer 保存 lyric、locked phoneme、velocity/consonant timing、accent、decay、opening、bend、portamento、vibrato type/length 與 normalized depth/rate envelope。

Native control domains 是：

```text
DYN BRE BRI CLE GEN POR PIT PBS
```

PIT 為 `-8192..8191`，PBS 為 `0..24` semitones，其他 master curves 為 `0..127`。所有範圍都在 Editor 前驗證。

### 5.3 Validation 是一個 stack，不是一個 boolean

每份 project 依次經過 Zod/input checks、semantic bounds/overlap/reference validation、temporary sibling write、XSD validation、selected native-loader fixtures、Editor integration，以及最後 atomic move。沒有任一層可以代替其他層。

### 5.4 第一份 from-zero agent proof

一個只能使用 Vocaloid MCP、不能使用 shell/raw XML 的 Codex session，從 abstract brief 建立 8 measures、132 BPM、4/4 的 original IA_ROCKS project：41 vocal notes、locked Japanese phonemes、34 DYN、6 PBS、22 PIT、expressive note styles、3 個 long-note vibratos。

它通過 schema 與 semantic validation；Yamaha loader 列舉出 351 objects、1 track、1 part。這證明 MCP 可以從 empty starting point 建立真正 native vocal project。

它還不是 finished song，因為尚無 accompaniment、mix、artifact history 或 delivery gate；但 generation 而非 template mutation 的核心主張已成立。

## 6. Phase III：安全自動化 original VOCALOID3 Editor

### 6.1 Command 與 dialog contract

Win32 menu enumeration 找到：

```text
File -> Export -> Wave...    command ID 33299
```

Export 是兩段 dialog transaction：VOCALOID 的 **Export Wave File** options，以及 Windows 的 **Export to Wave File** Save dialog。Dialog window 出現時，child controls 未必已建立，尤其在 offscreen/no normal Explorer shell 的環境。

### 6.2 第一個 cleanup crash

Prototype 太早 enumerate Save dialog，找不到 filename control，然後在 modal 仍 active 時關閉 disabled MFC owner，導致 VOCALOID3 access violation。

這不是 synthesis bug，也不是 malformed VSQX，而是 automation state-machine bug。

修正版會等待 filename/Save controls、只 hook `EVENT_OBJECT_SHOW`、依 title/structure/process owner 識別 dialog、先取消 known modal、等待 owner enabled、必要時只 terminate helper-owned process，且不向未知 UI state 盲送 close。

Save 後還要觀察 output 在四次 250 ms check 中穩定。Pre-Send adjustment 必須由 caller 明確允許，而且 result 區分 permission、dialog observed 與 adjustment actually accepted。

### 6.3 Singer substitution 必須 fail closed

若 requested voice unavailable，Editor 可能詢問是否改用 default singer。自動按 Yes 會得到 valid-looking audio 和虛假 provenance。

Helper 會 match dialog、回傳 `singer_unavailable`、拒絕 render。`list_voices` 只說 metadata exists；成功 `probe_voice` 才證明 current Editor 能合成 exact component。

### 6.4 Render 是 transaction

`vocaloid_render_wav` 會 validate VSQX、fingerprint binaries、acquire host-wide lease、選 temporary WAV、launch/observe/cancel、等待 stable output、parse RIFF/PCM、拒絕 silence/malformed sample count、atomic rename、release lease、cleanup owned process。

Existing destination 需要 explicit overwrite，並先建立 timestamped backup。失敗 render 不得在 requested final path 留假檔案。

### 6.5 Fingerprint、progress、cancel 與 lease

Bridge 只認 pinned Editor 3.2.1.1；unknown fingerprint 預設拒絕。Progress 暴露 validating、fingerprinting、lease、launching、synthesizing、verifying、committing、cleanup 八個 stage。

Host lock 在 `build/runtime/vocaloid-editor-render.lock`，包含 lease ID、PID、request ID、acquired time。只有 age threshold 加 dead-owner check 才能 reclaim；release 仍需 matching lease ID。這防止兩個 agent 同時搶一個 desktop Editor。

### 6.6 第一批 hardened exports

| Project | Helper runtime | Audio | Peak | RMS |
| --- | ---: | --- | ---: | ---: |
| Japanese `4 a` smoke | 13.657 s | 10.008 s，44.1 kHz，16-bit stereo | -18.47 dBFS | -38.46 dBFS |
| Codex-created `雨のあとで` | 14.641 s | 16.370 s，44.1 kHz，16-bit stereo | -7.92 dBFS | -23.01 dBFS |

到這裡，最小閉環成立：agent 建 project，original Editor 輸出 non-silent audio，而且不留下殘餘 process。

## 7. Phase IV：從 vocal snippet 到 structured song

### 7.1 Song-scale model

`vocaloid_create_song` 支援 multi vocal tracks/mixer、multi named parts、tempo/meter maps、measure/beat/tick positions、mono/stereo audio parts、tempo-aware duration 與 pre-measure-aware placement。這是 lead、harmony、backing 第一次能同時存在同一 project。

一份 integration fixture 含 2 simultaneous IA tracks、1 stereo backing、6 notes、4 DYN、1 WAV part；result 為 6.014 s、stereo、non-silent，peak -13.26 dBFS、RMS -25.32 dBFS。

### 7.2 Audio parts 是 reference，不是 embedded assets

VOCALOID audio part 只引用外部 WAV。Server 在寫 project 前驗證 16-bit PCM、44.1/48/96 kHz、mono/stereo、RIFF structure，並自行計算 play time。WSL path 還必須轉成 Windows-readable path；移動 WAV 就會破壞 reference。這是 reproducibility 必須公開的行為。

### 7.3 為什麼 accompaniment 可以內部用 MIDI，但產品不能停在 MIDI

FluidSynth 2.3.4 與 FluidR3 GM 成為第一個 deterministic backend。Canonical arrangement 保存 typed notes、drum hits、tempo/meter、mixer、patterns、placements；renderer 才暫時轉成 format-1 SMF、呼叫 FluidSynth、驗證 PCM、刪除 temporary MIDI。

MIDI 是一個 renderer 的 internal transport；vocal performance 仍是 native VSQX/original Editor；未來 VST/DAW backend 可替換 FluidSynth，而 stable song positions 不變。

FluidR3 GM 明確只是 **draft-quality** timbre backend。Program 106 被命名為 shamisen，不代表它有真實三味線演奏法。

### 7.4 16-measure experiment

第一首 song-scale experiment 有 intro、verse、pre-chorus、chorus、128→132 BPM、176 pitched notes、127 drum hits、56 lead notes、12 harmony notes。Original-Editor master 40.263 s。

結構成功，聲音卻暴露下一層缺陷：raw export 約 -9.0 LUFS、13.5 LU LRA、+0.3 dBTP，且有 9,844 個 full-scale samples。那不是 master，而是 clipped source。於是 audio-quality plane 成為必要工作。

## 8. Phase V：長曲、快速歌詞、配器與 mastering

### 8.1 Phrase compiler

`vocaloid_compile_vocal_phrase` 接受 1/16、1/32、1/64、dotted、tuplet、rest、gate、pitch、velocity、style、vibrato、sequential lyric allocation 與 explicit melisma index。

同一 lyric index 重複時，native continuation 是：

```text
lyric="-"
phonemes="-"
```

這讓 agent 表達 rapid syllabic passage 或 melisma，不需手工管理每顆 low-level note，也不創造非原生格式。

### 8.2 Reusable patterns 與 placements

長曲不能輸入幾千個重複 events。Arrangement 將 compact pattern 與 placements 分離；placement 可選 section、repeat、transpose、velocity scale 等 bounded transform。

一個 reference 只用 8 source events 與 2 placements，就展開成 96 measures、192 shamisen notes、384 drum hits，仍 deterministic 且可檢查。

### 8.3 Audio analysis 與 two-pass mastering

Analyzer 結合 PCM inspection 與 FFmpeg EBU R128，回報 duration、format、sample peak、RMS、crest、LUFS、LRA、true peak、full-scale count、per-channel levels 與 imbalance。

Masterer 寫新 output，執行 measured two-pass normalization，再重新分析，絕不相信 request 本身。它也明確承認：loudness normalization 無法還原已被 clipping 摧毀的 transient。

修正後 16-measure experiment 為 -13.8 LUFS、-1.0 dBTP、zero full-scale samples。後續也加入 true-peak corrective gain 與 +0.05 dB bounded tolerance。

### 8.4 96-measure stress test

`月影疾走` 有 172.408 s、96 measures、10 tempo events（96–156 BPM）、4/4→6/8→4/4、9 instrument/drum roles、81 placements、3,128 pitched events、861 drums、311 lead notes、85 harmony notes、41 controls。

第一版 vocal mix 嚴重偏左，因為 agent 以為 pan `0` 是 center。VOCALOID native mixer 實際為：

```text
0   = hard left
64  = center
127 = hard right
```

結果 L/R RMS 相差 17.196 dB。加入 mixer inspection/update、schema docs 與 per-channel analysis 後，lead=64、harmony=96，raw balance 改到 0.583 dB；final master -14.2 LUFS、-1.0 dBTP、zero clipping、12.6 LU LRA。

LRA target 是 9 LU，因此系統誠實回報 miss，沒有拿其他綠色 metrics 冒充 full success。另一次 Editor 無 WAV exit，也因 temporary/verify/atomic commit 沒留下假 artifact，retry 後才成功。

### 8.5 Artifact naming 也是 usability

```text
<song>-backing-v1.wav
<song>.vsqx
<song>-mix-v1.wav
<song>-master-v1.wav
<song>-<style>-final.wav
```

Song slug、role、version 可以大幅降低 accidental reuse。對 agent workflow 而言，清楚名字不是 cosmetic detail。

## 9. Phase VI：canonical song manifest

### 9.1 為什麼 VSQX 不能繼續當 database

完整 production 需要 semantic sections、chord intent、arrangement renderer settings、stable identities、stem dependencies、mix chains、analysis、history 與 source hashes。把它們塞回 mutable XML comment，只會讓 staleness 無法推理。

因此 `*.song.json` 是 canonical source，所有 media 都是 derived artifacts。

### 9.2 Manifest domains

Manifest 分為 timeline、sections、harmony、vocals、arrangement、mix、artifacts、review 八個 bounded domains。Song、section、voice、track、part、phrase、note、control、pattern、placement、effect、automation、artifact、review 都有 global stable ID。

### 9.3 三個 hashes 回答三個問題

- `content_hash`：完整 canonical document，排除自身 hash field；
- `composition_hash`：排除 downstream mix、artifact、revision/timestamp；
- `mix_hash`：current composition identity + current mix intent。

EQ 變更不應讓 raw vocal stems stale；melody 變更必須讓 stems、mix、delivery stale；review note 只改 content history，不假裝 composition changed。

### 9.4 Optimistic concurrency

每次 mutation 帶 `expected_revision`。Server validate、compare revision、apply one bounded mutation、increment、record parent hash、re-hash、temporary write、atomic rename。若另一 call 已前進，寫入失敗並要求 re-inspect。

Same-path mutation 建 timestamped backups；restore 不倒退 revision，而是建立一個以歷史 content 為基礎的新 revision。

### 9.5 Stable IDs 讓 bounded work 成立

「把第二次 chorus harmony 調小」不應變成危險的 array-index mutation。Stable ID 讓 agent 只 fetch 一個 section、更新一個 phrase、transpose selected events、維持 referential integrity、attach exact review note、產生 music-aware history diff。

Server 拒絕 zero-match transform、dangling references、invalid empty phrases、out-of-bounds placement 與 ID collision。

### 9.6 Dry-run 走真正 mutation path

Dry-run 把 manifest 複製到 temp path，呼叫相同 mutation logic，回傳 predicted revision/hashes、music-aware diff、preflight 與 exact result shape，最後刪除 temp。它回答的是「這個確切 call 會做什麼」。

### 9.7 Artifacts 是 dependency graph

Artifact record 由 server 計算 stable ID、role、path、bytes、SHA-256、source revision、composition/mix hash、dependencies、renderer/audio/analysis metadata。

Currentness 是 recursive：composition artifact 比 composition hash；mix artifact 比 mix hash；delivery 只有在自身 identity 與所有 dependency 都 current/readable 時成立。

這修正了一個 subtle bug：舊 mix 雖仍存在，但 mix intent 變更後不能繼續滿足 current delivery gate。

### 9.8 Build 是 provenance transaction

`vocaloid_build_song_manifest` 在一個 manifest-aware operation 裡 preflight、render accompaniment、compile/validate VSQX、compute digests、record dependency。只有所有 outputs verified 才 commit artifact records；失敗 transaction 產生的 files 不得被登記成 partial success。

這是「一堆 scripts」變成 production state machine 的時刻。

## 10. Phase VII：日文歌詞與可檢查 tuning gesture

### 10.1 Manual-backed G2P

Japanese G2P 僅使用 local VOCALOID3 manual 記載的 phoneme inventory，處理 hiragana/katakana、yoon、long vowels、moraic nasal、foreign kana、affricate 與 nasal-g options。

Kanji 必須提供 explicit kana reading；tool 不用 opaque dictionary 偷猜。Evidence chain 清楚分層：

```text
original lyric text
    -> supplied kana reading
    -> normalized reading
    -> mora units
    -> manual-backed phonemes
    -> rhythm alignment
```

### 10.2 Small `っ` 要變成 timing，不是虛構 phoneme

Manual inventory 沒有 small `っ` standalone token。系統要求明確策略：positioned rest，或 experimental `attach_next`。`ヴ` 的 fallback 也要顯式保存。Irregular pronunciation 是 evidence，不是隱藏例外。

### 10.3 Mora alignment 與 rapid lyrics

`sequential` 按 voiced cells 分配 successive mora；`explicit` 指定 mora index，repeated index compile 成 native `-` continuation。Stable event IDs 在 tuning 前就建立，後續 gesture、analysis、review 不再依賴 array index。

### 10.4 Gesture compiler，不是 opaque preset

Agent 更容易思考「soft entrance」「restrained scoop」「open chorus timbre」，而非幾十個 raw PIT samples。Gesture layer 支援 articulation、vibrato、pitch scoop、dynamics/opening/timbre arcs，並 compile note velocity、accent、decay、opening、bend、portamento、vibrato 與 sparse master curves。

Intent 與 numeric result 都保留，沒有不可檢查的 “make it emotional” preset，也不對 rendered audio 做自動 pitch quantization。

### 10.5 Guardrail 要容許 intentional extremity

系統檢查 tessitura、leap、phrase length、breath、consonant collision、mora density 與 harmony risk，但不一律禁止高密度或 dissonance。Vocaloid 風格常依賴 rapid lyrics、abrupt register 與 synthetic precision。

### 10.6 Voice readiness 是 active probe

IA_ROCKS probe 產生一份 `ら`／`4 a` small project、center mixer、locked phoneme，透過 original Editor render、驗證 non-silent 後刪除 temp。Cache key 綁 voice component 與 editor/helper fingerprints；verified 7 days、unavailable 24 hours、transient error 10 minutes。VVD discovery 永遠不能取代 synthesis proof。

## 11. Phase VIII：stems、score/render 分析與可重現混音

### 11.1 Instrument stems

每個 pitched/drum track 由 configured backend 單獨 render。Agent 明確選 preserve authored pan/effects 或 centered/dry。每份 stereo non-silent result 綁 track ID、composition hash、digest、renderer metadata。

### 11.2 Vocal stems

對每個 vocal track，workflow 驗證 VSQX digest/hash、建 temp project、mute other vocals、physically remove backing audio part、選 center/volume override、透過 Editor render、verify WAV、record dry/center decisions and dependencies。直接 remove backing 是避免 hidden contamination 的額外保險。

### 11.3 兩種 timeline origin

Instrument stems 從 `song_start` 開始；Editor vocal stems 從含 pre-measure 的 `project_start` 開始。Mix renderer 計算 tempo-aware pre-measure duration，延遲正確一側後才 sum。Timeline origin 是 artifact metadata，不靠 audible onset 猜。

### 11.4 Score-versus-render vocal analysis

`vocaloid_analyze_vocal_stem` 把 stable note events 對齊 isolated WAV，以 8 kHz mono、40 ms frame、10 ms hop 與 expected-note-constrained YIN-style F0，回報 contour、cents error、voiced ratio、energy/voiced onset、consonant lead、release、vibrato depth/rate/regularity。

短於約 120 ms 的 event 標記 resolution-limited；continuous voiced boundary 特別處理。Output 是 observation，不 auto-shift score，也不聲稱 phoneme recognition、intelligibility 或 emotion detection。

### 11.5 Composition 與 mix identity 分開

改 EQ、fader 或 section ramp 只改 `mix_hash`，昂貴 raw stems 仍可重用。這讓「bridge vocal brighter」變成 deterministic remix，而不是再次啟動數分鐘 Editor export。

### 11.6 Typed effect chains

支援 gain、pan、HPF、LPF、parametric EQ、compressor、de-esser、bounded room/reverb、delay、limiter。Disabled effects 保留 intent 但 skip。沒有 hidden normalization、centering 或 makeup gain。

```text
decode / resample / stereo float
    -> timeline alignment
    -> track automation
    -> ordered track effects
    -> sum (normalize disabled)
    -> bus automation/effects
    -> PCM encoding
    -> independent analysis
```

Requested graph 與 final FFmpeg graph 都保留為 evidence。

### 11.7 Preview、A/B 與 review notes

Section automation 綁 semantic section IDs。Review layer 可 render bounded preview、loudness-matched A/B、保存 provenance，並把「chorus-2 consonants blur」這類人耳觀察綁到 exact section/object/artifact，而不是消失在 chat 裡。

## 12. Phase IX：preflight、host readiness、history 與 delivery

### 12.1 一次 read-only whole-song pass

`vocaloid_preflight_song` 預設不開 Editor，檢查 structure/bounds、vocal overlap、voice/phoneme evidence、density/breath、harmony/tessitura、arrangement、mixer、artifact provenance、host readiness。

它能報 overlapping notes、out-of-bounds objects、unlocked phonemes、rapid density、consonant collision、missing breath、large leaps、non-chord tones、minor-second collision、extreme pan、unverified voice、missing/stale/hash-mismatched artifacts，以及 native 256-character comment boundary。

那個 comment rule 來自真 failure：Hanairo 的 long comment 高層 preflight 通過，VSQX build 才失敗。加入 `NATIVE_TRACK_COMMENT_TOO_LONG`／`NATIVE_PART_COMMENT_TOO_LONG` 後，deterministic error 被移到昂貴 build 前。

### 12.2 Readiness 分 stage

- **score readiness**：canonical music 可解讀；
- **build readiness**：可 compile score 與 accompaniment；
- **render readiness**：current VSQX 與 verified voice/host 可用；
- **mix readiness**：current stems 存在；
- **delivery readiness**：current mix/master dependencies 與 QC 成立。

Fresh song 可以 score-ready 而 render-not-ready，因為尚未 build VSQX；這是準確 workflow state，不是 failure。

### 12.3 History、diff 與 monotonic restore

History 掃 current manifest 與 timestamped backups，驗證每個 candidate，顯示 timeline/vocals/arrangement/mix/artifacts/review domains 的差異。Restore 把歷史 content 帶入新 revision，不抹除 intervening history。

### 12.4 Manifest-aware mastering/delivery

Master operation 從 current manifest mix artifact 起步，不接受任意 WAV。Delivery 驗證 digest、dependencies、source hashes、stereo/format、LUFS tolerance、LRA policy、true peak、zero clipping、balance 與 reviews。

通過後才把 hash-identical listening WAV 與 current-composition VSQX 以同 basename 發布。Existing identical target 可 reuse；same-name different bytes 絕不 silent overwrite。VSQX 保存 score/tuning/mixer/backing reference；isolated-stem final mix/master 仍由 manifest provenance 表達，而不是回嵌 project。

## 13. Phase X：為 agent 重設計 MCP

### 13.1 Context friction 是產品 bug

某 checkpoint 的 flat MCP 有 37 tools，serialized definitions 153,222 bytes，粗估約 38k tokens，且都回 generic untyped `data`。Fresh Codex inspection 花 34,774 tokens。

這不是「agent 不夠聰明」，而是 product defect。修法是 profiles、on-demand resources、concrete outputs。當時量測：production 20 tools/77,905 bytes、full 49/217,352 bytes、legacy-vsqx 16/60,818 bytes，並暴露 9 resources。

### 13.2 Workflow tools 與 low-level tools 服務不同角色

Full profile 保留 note/curve/mixer/raw render 等 diagnosis tools；production profile 聚焦 canonical create/inspect/edit、align lyrics、preflight、build、stems、analyze/mix、review、master/delivery、history。

API coverage 還在，但日常 agent 不必在幾十個相近操作中迷路。

### 13.3 Resources 讓 static reference 不必出現在每次 call

Capabilities、from-zero example、optional supplied lyrics、wa-rock／J-Rock／summer-night／piano-ballad／electro palettes 以 on-demand resources 提供。Exact example 是在 fresh agent 需要六次 schema correction 後加入的：description 不足以取代可直接照著理解的 valid sequence。

### 13.4 Typed outputs 是 routing reliability

每個 production tool 宣告 concrete output schema。Three-song closure 真的抓到 schema drift：master/delivery side effects 成功後，MCP client 卻因 output schema 漏掉 `sourceRevision`、`manifestContentHash` 回 `-32602`。Typed output 是執行中的 public contract，不是裝飾文件。

### 13.5 Annotation 會改變 agent behavior

Fresh evaluation 一直取消 `vocaloid_edit_song(dry_run=true)`；直接 stdio 只需 256 ms。原因是 static `destructiveHint: true`。改為符合 actual recovery contract 的 non-destructive annotation 後，safe preview 才不被 agent 合理拒絕。

### 13.6 Actionable errors 降低 retry loops

Errors 區分 stale revision、editor busy、singer unavailable、unknown fingerprint、missing/stale/hash-mismatched artifact、stage blocked、out-of-bounds、zero-match、invalid phoneme、silent/malformed WAV，並盡量附 current revision/hash、blocking ID、expected dependency 或 next safe action。

### 13.7 Public MCP 才是產品邊界

Canonical writes、preflight、build、Editor render、mix、master、review、artifact hashes 與 final QC 必須走 public MCP。直接呼叫 TypeScript function 只能證明 implementation；real agent 是否看得懂 description/schema/resource/annotation/output，只有 protocol evaluation 會暴露。

## 14. 完整 production workflow

1. 選 `VOCALOID_MCP_PROFILE=production`，讀 capabilities、from-zero example 與 selected style。
2. 用 host readiness 與 cached voice probe 分離 binary/lease/voice dependency。
3. 只建立 timeline、sections、harmony 與 renderer skeleton。
4. 以 stable IDs 一次寫一個 bounded section/domain：inspect → dry-run → diff/preflight → apply。
5. 先 align Japanese lyrics 建 stable notes，再 apply tuning gestures。
6. 用 semantic roles、patterns、placements、seeded groove 建 arrangement。
7. 在昂貴 artifact 前 preflight，將 warning 分成 defect、renderer limit、intentional style。
8. Build backing + native VSQX，同一 immutable composition revision 下記錄 digests/dependency。
9. Lead/harmony 各自一個 immutable render transaction；成功一軌就 commit 一軌。
10. 分析 score/render pitch、timing、voicing、release、vibrato，但 recommendation 只 advisory。
11. 以 stable target author effect chains 與 section dynamics；mix-only change 重用 stems。
12. Render stem mix、量測、preview、loudness-match A/B、寫 structured listening notes。
13. 從 current manifest mix mastering，不從 directory 裡猜「最新 WAV」。
14. Final gate 驗證 voice、build/stems/mix currentness、format、LUFS/LRA/peak/clipping/balance 與 warnings disposition。
15. 只在 gate 通過後，發布 matching WAV/VSQX；修改時保留 history，composition change 自動 stale downstream artifacts。

這才是 closed loop：

```text
compose -> render -> observe -> revise -> deliver
```

## 15. 獨立 agent evaluations

### 15.1 MCP-only from-zero creative evaluation

一個 ephemeral `codex-cli 0.144.5` 環境只能使用 Vocaloid MCP，禁止 shell、filesystem、network、source VSQX 與其他 MCP。Agent 從零建立四小節 `星駆ける声`：revision 7、2 kana-aligned phrases、12 notes、native `-` melisma、5 gesture classes、12 controls、Celesta/drums、valid VSQ3 與 non-silent stereo backing。

它找到真 defect：control points 只在 curve type 內排序，沒有按 native 全域順序，觸發 Pre-Send adjustment。Writer/validator 修正後，automation 預設拒絕 Pre-Send；caller 必須 explicit allow，result 記錄 dialog 與 acceptance。

IA_ROCKS 綁定確認後，Editor render 13.328 s audio；early master 約 -22 LUFS/-13.3 dBTP，delivery version -16 LUFS、7.9 LRA、-7.2 dBTP。

### 15.2 Production-profile routing evaluation

第二個 ephemeral read-only Codex 只可使用 20 production tools/resources。第一輪抓到 destructive annotation 與六次 schema corrections；加入 exact from-zero resource 後，clean rerun 只透過 public MCP 建立 `production-profile-agent-smoke-v2.song.json`：revision 3、1 IA_ROCKS voice/track/part/phrase、6 vocal events、1 guitar track/4 events、zero preflight findings，score/build ready；render 尚未 build，因此正確為 false。

### 15.3 兩種 evaluation 缺一不可

第一個問題是「isolated agent 能否創作並 compile native performance？」第二個問題是「fresh agent 不讀 source 能否操作 production API？」兩者共同防止兩種自欺：只有作者知道怎麼用的強大 implementation，以及介面漂亮但從未渲染真聲音的 pipeline。

## 16. 三種完整 style closure

### 16.1 `花色日和` — wa-rock

使用者提供的 lyric file 保持 local/untracked，只在 manifest 保存 SHA-256 `dcee0aaae443d01a3bc0a32fb2cd3e2bff55d09acdcca0ad52d22bc499829949`。Original text、romanization、derived kana、normalized reading、phonemes、overrides 與 source evidence 分開保存。

- revision 41、146 measures、820 vocal events；
- lead + 13 selective harmony destinations；
- 4/4→6/8→4/4、9 tempo points、7 arrangement tracks；
- shamisen、koto、shakuhachi、taiko、guitar、bass、drums；
- final 256.474 s、-15.2 LUFS、5.7 LRA、-1.10 dBTP、zero clipping、-1.14 dB balance；
- WAV SHA-256 `39723f64e976601e7c86390025fe7537164423e507041eede4beedb941d0c254`。

Intentional rapid passages 保留 112 consonant-collision 與 8 high-density warnings；obsolete `stem-mix-r26` 留在 history，但不滿足 current delivery。

```text
artifacts/songs/hanairo-biyori-wa-rock-ia-rocks-final.wav
artifacts/vsqxs/hanairo-biyori-wa-rock-ia-rocks-final.vsqx
```

### 16.2 `火花の航路` — driving J-Rock

- revision 25、78 measures、433 vocal events、lead + 8 harmony phrases；
- 一次 2/4 turnaround、9 tempo points、6 arrangement tracks；
- double guitars、bass、piano、strings、drums；
- final 126.564 s、-14.0 LUFS、4.8 LRA、-1.00 dBTP、zero clipping、+1.16 dB balance；
- WAV SHA-256 `53b96224b6d8791c320785f857bc5777f2a5208e214199739d808480d1c86626`。

指定 rapid cells 保留 50 consonant-collision 與 5 density warnings。

```text
artifacts/songs/hibana-kouro-ia-rocks-j-rock-final.wav
artifacts/vsqxs/hibana-kouro-ia-rocks-j-rock-final.vsqx
```

### 16.3 `夏の夜に浮かぶ声` — summer-night dream pop

- revision 26、78 measures、411 vocal events、lead + 7 harmony phrases；
- 重複 6/8↔4/4、8 tempo points、6 arrangement tracks；
- two pads、bells、clean guitar、fretless bass、soft kit；
- final 198.001 s、-17.2 LUFS、9.6 LRA、-1.50 dBTP、zero clipping、+0.26 dB balance；
- WAV SHA-256 `5bb246d2eaf0262a2495a97e4690aa1ceced62a476f3234f06d794ba09a4daaf`。

這份 manifest 為 zero errors、zero warnings。

```text
artifacts/songs/natsu-no-yoru-ia-rocks-dream-pop-final.wav
artifacts/vsqxs/natsu-no-yoru-ia-rocks-dream-pop-final.vsqx
```

三首歌的 score/build/render/mix/delivery readiness 都通過。Warnings 是 listening targets，不等於 current graph invalid。Blocking every style risk 會讓 guardrail 接管作曲；完全 suppress warning 又會失去 review 目標。

### 16.4 真 failure 驗證 resume

一次 long summer harmony export 在 `wait_for_wave` 退出。Renderer 釋放 lock、沒有登記假 artifact；但舊 batch cleanup 也刪了已成功 lead output。

Runner 改成每個 vocal track 一個 transaction，中間 1.5 s quiet period；resume 依 current composition hash 與 immutable artifact 判斷。它 reuse 已 commit lead，只重 render missing harmony，最後完成 mix/delivery。Recovery 不是從 code 推測，而是被真 failure 強迫驗證。

## 17. Failure ledger

| Failure／錯誤假設 | Symptom | Root cause | Response |
| --- | --- | --- | --- |
| `4 a` 被當非法 | native load failure | 錯誤直覺；`4` 是官方 flap | manual + native regression |
| XSD valid 仍不相容 | schema pass、loader fail | raw phoneme/note style/vibrato/CDATA conventions | 加 Yamaha loader validator |
| DSE `-100` | Daisy/engine load 後無 WAV | undocumented registration context | 停在 licensing boundary，改用 Editor |
| Save controls 不存在 | 無法輸 filename | dialog children asynchronous | bounded wait for exact controls |
| Cleanup access violation | Editor crash | modal active 時關 disabled owner | cancel modal first，只處理 owned process |
| Singer substitution | default singer prompt | metadata 不等於 availability | fail closed + active probe |
| 16-bar master clipping | +0.3 dBTP、9,844 full-scale samples | 把 WAV exists 當完成 | PCM/EBU analysis + measured master |
| 96-bar hard-left | 17.196 dB imbalance | 誤以為 pan 0=center | 0/64/127 docs + channel QC |
| LRA target miss | 其他 metrics pass | loudness 與 dynamics 不同 | honest partial pass |
| Editor 無 WAV exit | final output 缺失 | legacy transient | temp + verify 防假 artifact，retry |
| Curve ordering | Pre-Send appeared | per-type sort 非 global native order | fix writer/validator，explicit Pre-Send |
| Voice component confusion | IA/IA_ROCKS 混淆 | duplicated guidance | canonical constant + active binding |
| Codex 取消 dry-run | safe preview 被拒 | wrong `destructiveHint` | annotation 對齊 recovery contract |
| Fresh agent 六次 schema correction | context/calls 浪費 | 無 exact workflow example | on-demand from-zero resource |
| Long comment build 才 fail | preflight 漏掉 | native 256-char bound | exact preflight codes |
| Old mix 看似 ready | stale artifact 被當 current | mix hash/dependency 不完整 | recursive currentness |
| Success 回 `-32602` | side effect 成功、response fail | output schema 少 fields | sync schema + protocol regression |
| True peak 微超標 | measured result over ceiling | loudnorm rounding/measurement | recorded corrective gain + remeasure |
| Harmony `wait_for_wave` fail | batch cleanup 刪成功 lead | shared multi-track transaction | per-track commits + resume |
| 37 tools generic output | context 過大 | coverage 沒 product design | profiles/resources/typed workflows |

幾乎所有 bug 都發生在 abstraction boundary：schema/native loader、metadata/licensed state、UI/modal lifecycle、intent/encoding、render/quality、existence/current provenance、server/client interpretation。

因此 general principle 是：每個 boundary 都要有 explicit contract，而且證據必須在 boundary 的另一端產生。

## 18. 測試與證據策略

### 18.1 當時 automated result

```text
tests:     47
passed:    45
failed:     0
skipped:    2
```

兩個 skip 是 licensed Editor stem export 與一份 user external WAV fixture。真 IA_ROCKS closures 另行執行了前者，但普通 unit run 不應每次佔用 desktop software。

### 18.2 Test pyramid

| Layer | 能證明 | 不能證明 |
| --- | --- | --- |
| Pure musical/unit | deterministic transform、bounds、IDs | Editor behavior、audio quality |
| Manifest/property | hash/revision/transaction integrity | 歌是否好聽 |
| File/format | VSQX/WAV structural facts | singer availability |
| Renderer component | effects/master/A-B contracts | GM timbre 是否真實 |
| MCP protocol | public schemas/resources/stdio | fresh agent 是否選對工具 |
| Native loader | Yamaha 接受 project | Editor 能否合成指定 singer |
| Editor integration | licensed app 輸出聲音 | full dependency currentness |
| Agent isolation | discoverability/routing | 多 prompt 統計品質 |
| Full closure | scale/provenance/resume/delivery | 人類藝術共識 |

Synthetic audio 只在 expected answer 精確時使用，例如 +100 cents、5 Hz vibrato、known clipping、known channel gains。它不能證明 IA 咬字清楚、chorus 令人興奮。Agent report 也必須由 root process 獨立檢查 manifest hash、counts、XSD、WAV、lease/process cleanup 與 artifacts。

當時 approximate checked-in lines：`src/` 16,801、tests 4,423、native C 1,320、style runner 1,405、notes 1,998。Line count 不是品質指標，但足以說明這不是短小 XML converter。

## 19. Chronological checkpoints

| Time (+08:00) | Commit | Checkpoint |
| --- | --- | --- |
| 15:31 | `0c64959` | bootstrap agent-driven VOCALOID3 MCP |
| 15:47 | `ce27169` | structured songs + native accompaniment |
| 16:03 | `088c253` | agent-composed instrumental backing |
| 16:29 | `45531e2` | long-form rhythm + mastering |
| 17:01 | `7a239e4` | stereo mixer revisions after hard-left failure |
| 17:31 | `5549379` | revisioned canonical song manifest |
| 17:44 | `d3e94c6` | provenance-linked stems |
| 17:57 | `efcf6dc` | score/render vocal analysis |
| 18:11 | `95c281c` | reproducible stem effects/section mix |
| 19:02 | `30e698a` | Japanese lyrics + tuning workflow |
| 19:24 | `ebf1425` | bind eval to IA_ROCKS |
| 19:33 | `758abd7` | close IA_ROCKS render/delivery loop |
| 19:54 | `76cec42` | capability/context audit |
| 21:48 | `6a4974d` | production composition/delivery workflows |
| 21:52 | `6d0d677` | exact IA_ROCKS guidance |
| 22:12 | `2513cb7` | production MCP routing hardening |
| 23:37 | `91545a0` | three-style IA_ROCKS closure |

架構不是一開始就完整畫好，而是從 evidence 演化：

```text
native uncertainty
  -> loader evidence
  -> from-zero project
  -> editor audio
  -> longer-song defects
  -> canonical state
  -> stems and analysis
  -> production provenance
  -> agent routing audit
  -> full-style closure
```

最早 10-tool surface 適合證明 create/inspect/edit/render；現在 profiles 把 low-level tools 留給 diagnosis，把 normal workflow 交給 canonical task-level operations。Coverage 與 usability 不必二選一。

## 20. Repository map 與 reproducibility

```text
vocaloid/
├── src/                         MCP、canonical state、compiler、render、mix
├── native/                      Yamaha loader probe、Editor export helper
├── scripts/                     native build、reference workflow、Win32 helpers
├── tests/                       unit、integration、protocol regressions
├── notes/                       contracts、evidence、failure analysis
├── artifacts/evals/             local-only builds/stems/mixes/analyses
├── artifacts/songs/             local-only final listening WAVs
├── artifacts/vsqxs/             tracked native projects
└── blogs/                        long-form retrospectives
```

Final WAVs 與大部分 evaluation media 故意不進 Git；較小的 native VSQX 可追蹤。User-supplied Hanairo lyrics 保持 untracked，只有 digest 進 manifest/report。

### Build/test

```bash
npm install
npm run build
npm test
scripts/build-native.sh
```

Draft accompaniment 另需 FluidSynth、SoundFont、FFmpeg。FluidR3 GM 是 reproducibility baseline，不是 quality ceiling。

### Start MCP

```bash
VOCALOID_MCP_PROFILE=production node dist/src/index.js
VOCALOID_MCP_PROFILE=full node dist/src/index.js
VOCALOID_MCP_PROFILE=legacy-vsqx node dist/src/index.js
```

### Isolated Codex example

```bash
codex exec --skip-git-repo-check \
  -c 'mcp_servers.vocaloid.command="node"' \
  -c 'mcp_servers.vocaloid.args=["/absolute/path/to/vocaloid/dist/src/index.js"]' \
  'Use only the Vocaloid MCP. Read its capabilities and from-zero example, then create and preflight a new canonical song.'
```

Strict evaluation 還應 disable other tools、filesystem、shell、network，才能區分 MCP usability 與 agent 偷讀 implementation。

## 21. 安全、provenance 與操作邊界

### 21.1 Filesystem safety

Writes 限制在 approved workspace，path crossing Windows 前 normalize/validate。Existing outputs 需 explicit overwrite；canonical files 有 timestamped backup；derived artifacts 優先 immutable versioned names。

```text
validate intent
    -> write/render temporary sibling
    -> verify complete content
    -> close verified output
    -> atomic rename
```

### 21.2 Process ownership 與 serialization

Exporter 只操控自己 launch 的 process；unknown Editor window 不可當 disposable。Host lease 防 concurrent automation；stale recovery 要 age + dead PID；release 要 matching lease ID。Failed call 不得留下 false artifact 或 dangling lock。

### 21.3 Identity boundaries 一律 fail closed

Unknown editor fingerprint、singer substitution、VVD-only metadata、filename-only artifact、stale mix、unapproved Pre-Send、silent/malformed WAV 都不能被推測成成功。

### 21.4 Licensing boundary

IDA/native probes 用於理解本地安裝、驗證 generated files 與 legitimate render path。Project 不 bypass activation、不 patch DSE、不散布 proprietary binary/voice database，也不聲稱 direct engine wrapper 取代 licensed Editor。

### 21.5 Provenance 必須 compute，不能由 caller 宣告

Server 在產生/讀取 artifact 後自行計算 digest、bytes、audio properties、source revision 與 dependency。Delivery 會 walk graph。Provenance 是 executable state，不是 description。

### 21.6 沒有 hidden “helpful” audio edits

Mix 不 silent normalize/center/limit/makeup；master 寫新 output；true-peak correction 記錄；score/render estimates 不自動改 pitch/timing。Agent 應能從 manifest 解釋 final audio 為何不同。

### 21.7 Local source-control discipline

Generated audio 不進普通 source commits；compact VSQX、code、evidence、notes 可追蹤。Final WAV 整個 directory ignored；user-supplied lyric/plans 不動。Remote push 永遠是獨立 explicit decision。

## 22. 已證明、未證明、下一步

### 22.1 有 concrete evidence 的能力

- 從零生成 native projects，不需 source VSQX；
- V3/V4 create/edit/validate 與 V3 native-loader fixtures；
- original IA_ROCKS synthesis；
- 96/146-measure long form、多 vocal roles、tempo/meter arcs；
- rapid Japanese lyrics、native melisma 與 inspectable tuning；
- GM multi-instrument arrangement、patterns、seeded groove；
- composition/mix hashes、isolated stems、deterministic mix；
- LUFS/LRA/peak/clipping/balance QC；
- manifest-aware master/delivery 與 matching VSQX；
- compact typed MCP、resources、isolated Codex evaluations；
- lease cleanup、false-artifact prevention、real-failure resume；
- stable IDs、dry-run、history/diff/restore。

### 22.2 還沒有跨過的邊界

最大的 audible limit 是 FluidR3 GM：它證明 arrangement、timing、roles、routing、renderer replaceability，不證明 release-grade guitars/drums/pads 或日式樂器 articulation。下一步應接 licensed VST/DAW/sample-library renderer，並保留 stable-track provenance 與 explicit keyswitch/articulation。

其他 open areas 包括：canonical MIDI/SMF import、CC/sustain/aftertouch/articulation、masking/phase/mono diagnostics、sidechain/subgroups/sends、reading candidate evidence、更多 legitimate voices 的 profile，以及 human listening workflow。

Numeric analysis 不能證明 lyric intelligibility、emotion、memorable hook、appropriate harmony、acoustic authenticity、mix excitement/fatigue 或 overall artistic quality。

兩個 isolated sessions 也不是 distribution。真正 benchmark 應統計 readiness success rate、invalid calls、context tokens、dry-run/apply ratio、stale revision recovery、wall/editor time，並做人耳 blind rating。

### 22.3 Practical next-step order

1. 接一個高品質 licensed accompaniment renderer；
2. 做 repeated multi-prompt routing benchmark；
3. 補 canonical MIDI/SMF、CC/sustain/articulation；
4. 加 masking、phase/mono、send/bus/sidechain；
5. 加 evidence-bearing Japanese reading candidates；
6. probe/profile 更多合法安裝 voices；
7. 擴展 human listening 與 reference-audio comparison。

Direct DSE activation 並非 priority。Original Editor 已提供合法且 verified 的 synthesis boundary；accompaniment quality 與 agent evaluation 更有 user-visible value。

## 23. 可泛化的工程教訓

1. **先定義 terminal artifact。** 若目標只是 MIDI，一個下午就完；「完整、可聽、可改、可驗證的歌」會讓缺失 layers 無所遁形。
2. **Schema 不完整時，用 vendor loader 當 oracle。** XSD 檢查 grammar，不代表 legacy app behavior。
3. **移到最高的合法穩定邊界。** Direct DSE 有趣，但依賴 undocumented registration；Editor 更誠實。
4. **UI automation 是 protocol state machine。** Button click 不是重點；ownership、modal、timeout、cleanup 才是。
5. **Creative intent 與 derived format 分開。** 這個 pattern 同樣適用 CAD、video、DAW。
6. **一個 hash 很少能回答所有 staleness。** Hash boundaries 應反映 dependency economics。
7. **長 session 中 stable IDs 勝過 array index。** Agent 用語意思考，不用陣列位置。
8. **Dry-run 應走 exact write path。** 另一套 validator 必然 drift。
9. **Tool 數量不是 agent capability。** Profiles、resources、typed outputs 才把 coverage 變成 usability。
10. **Protocol metadata 是 executable behavior。** Wrong annotation 或少一個 output field 都會改變結果。
11. **Warnings 引導 taste，不取代 taste。** Error 留給不真實／不可解讀狀態。
12. **測 recovery，不只 happy path。** 真 harmony failure 比另一個 clean render 更有價值。
13. **在每個昂貴 boundary 的另一端量測。** XML 後 native load、render 後 parse WAV、master 後 remeasure。
14. **在 API 保存 uncertainty。** Metadata found ≠ voice available；warning ≠ bad；F0 estimate ≠ wrong note；GM role ≠ authentic instrument。

## 24. 附錄：production tools 與 resources

本文 checkpoint 的 20-tool production profile 包括：

| Tool | Purpose |
| --- | --- |
| `vocaloid_host_readiness` | fingerprints、lease、cached voice evidence |
| `vocaloid_probe_voice` | bounded original-Editor synthesis proof |
| `vocaloid_align_japanese_phrase` | reading/mora/phoneme/rhythm alignment |
| `vocaloid_create_song_manifest` | revision-1 canonical skeleton |
| `vocaloid_import_vsqx_manifest` | import V3/V4 score with provenance |
| `vocaloid_edit_song` | bounded dry-run/apply mutations |
| `vocaloid_inspect_song_manifest` | hashes/revision/domain/artifact summary |
| `vocaloid_preflight_song` | issues + stage readiness |
| `vocaloid_get_song_section` | bounded semantic section read |
| `vocaloid_build_song_manifest` | backing + validated VSQX transaction |
| `vocaloid_render_instrument_stems` | per-arrangement-track stems |
| `vocaloid_render_vocal_stems` | original-Editor isolated vocals |
| `vocaloid_analyze_vocal_stem` | score/render observations |
| `vocaloid_render_stem_mix` | deterministic effects/automation/sum |
| `vocaloid_render_manifest_master` | current VSQX Editor master |
| `vocaloid_master_manifest_delivery` | bounded mastering + provenance |
| `vocaloid_review_audio` | preview + loudness-matched A/B |
| `vocaloid_review_song` | qualitative listening notes |
| `vocaloid_manifest_history` | list/diff/monotonic restore |
| `vocaloid_analyze_wav` | PCM + EBU R128 analysis |

On-demand resources 提供 capabilities、from-zero example、style palettes，以及當本地 user-supplied lyrics 存在時的 optional authority resource。它們讓重要 reference 可用，又不必塞進每次 tool schema。

Artifact vocabulary：canonical manifest 是 revisioned truth；composition artifact 綁 `composition_hash`；mix artifact 綁 current composition + `mix_hash`；delivery 必須 recursive current；historical artifact 可比較但不能滿足 readiness。

Audio metrics 也有明確邊界：LUFS 是 program loudness，不是 impact；LRA 是 policy/風格選擇；true peak 要 processing 後重測；zero clipped samples 不證明 upstream 從未 clip；channel balance 可有 intentional asymmetry；F0/onset/vibrato 是 observation，不是 intelligibility 或 taste。

詳細 evidence 可參考：

- [`notes/synthesis-reverse-engineering.md`](../notes/synthesis-reverse-engineering.md)
- [`notes/long-form-workflows.md`](../notes/long-form-workflows.md)
- [`notes/song-manifest-design.md`](../notes/song-manifest-design.md)
- [`notes/song-manifest-workflows.md`](../notes/song-manifest-workflows.md)
- [`notes/stem-mix-workflow.md`](../notes/stem-mix-workflow.md)
- [`notes/score-render-analysis.md`](../notes/score-render-analysis.md)
- [`notes/japanese-lyrics-and-gestures.md`](../notes/japanese-lyrics-and-gestures.md)
- [`notes/codex-mcp-v1-eval.md`](../notes/codex-mcp-v1-eval.md)
- [`notes/production-profile-eval-2026-07-18.md`](../notes/production-profile-eval-2026-07-18.md)
- [`notes/capability-audit-2026-07-18.md`](../notes/capability-audit-2026-07-18.md)
- [`notes/style-eval-closure-2026-07-18.md`](../notes/style-eval-closure-2026-07-18.md)

---

## 結論

這個專案現在完成了原始問題真正要求的事：讓 agent 從空白 timeline 走到一首完整、native、rendered、mixed、mastered、verified 的 VOCALOID 歌，並同時交付 final listening WAV 與 matching current-composition VSQX。

最重要的成果不是某一個 tool 或某一個 WAV，而是 closed evidence loop：

```text
creative intent
  -> canonical revision
  -> native score and rendered stems
  -> measurable audio
  -> bounded listening/revision
  -> current dependency graph
  -> final delivery
```

這個 loop 穿過了真正的 failure：phoneme 誤診、UI cleanup crash、licensing boundary、clipping、hard-left pan、LRA miss、curve ordering、agent annotation friction、native comment limit、stale mix provenance、output-schema mismatch、true-peak overshoot，以及 long harmony export failure。每一個 failure 都讓 public contract 更誠實。

仍有很多工作：FluidR3 GM 不是 release-grade band；只有 IA_ROCKS 在這個 checkpoint 有 complete evidence；numeric analysis 不能決定一句歌詞是否打動人；MIDI import、advanced articulation、sidechain/bus、spectral diagnostics、更多 voice profiles 與 statistical agent benchmark 都還沒完成。

但邊界已經徹底改變。

這不再是一個 note generator、MIDI converter 或 VSQX demo。它是一件 agent-facing production instrument：有 native synthesis、durable creative state、reproducible audio operations、recovery semantics，以及誠實的 final checks。

也就是一個足夠好的基礎，讓 agent 與人真的可以一起做完整的 Vocaloid 音樂。