note-to-html 不支援 Notability 現行的 .ntb 容器（FlatBuffers），只認舊的 plist-based .note

[kiki830621]

Problem

Notability 的現行筆記容器是 .ntb（實測 app 版本 16.8.1），而 note-core-swift
的 NoteParser 只認舊的 plist-based .note。拿現在的 Notability 匯出檔跑
note-to-html，一定失敗。

實跑（macdoc 0.5.0）：

$ macdoc convert --to html --css light <note-bundle> --output out.html
Error: 找不到 Session.plist，可能不是 Notability 筆記檔

錯誤訊息本身是對的（檔案裡確實沒有 Session.plist），但它會把使用者導向錯誤的結論
——「這不是 Notability 檔案」。實際上它就是 Notability 檔案，只是新世代容器。

Type

feature

Expected

note-to-html 能吃現行 Notability 版本匯出的筆記；或者，若本專案決定不支援新容器，
錯誤訊息要明講「偵測到新版 .ntb 容器，目前僅支援舊版 .note」而不是暗示檔案不對。

Actual

Parser 從頭到尾找 plist，對新容器沒有任何解析路徑，錯誤訊息把格式世代問題誤報成
「不是 Notability 筆記檔」。

兩種容器的差異（實測）

	目前支援的 .note	現行 .ntb
外層	zip	zip（PK\x03\x04，compression method=store）
文件本體	Session.plist	noteBundle — FlatBuffers
手寫索引	HandwritingIndex/index.plist	index/ios/HandwritingIndex.fb — FlatBuffers
錄音索引	Recordings/library.plist	index/ios/RecordingIndex.fb — FlatBuffers
錄音檔	Recordings/*.m4a	assets/<sha512>.mp4（AAC；bundle 內字串標為 audio/mp4）
其他	—	version（內容為 1）、manifest.json（{"appVersion":"16.8.1"}）、thumbnail.png

unzip -l 的實際條目（一則含兩段錄音的筆記）：

        1  version
   826824  noteBundle
 14539950  assets/<sha512-a>.mp4
  5014938  assets/<sha512-b>.mp4
       29  manifest.json
    11816  index/ios/HandwritingIndex.fb
       88  index/ios/RecordingIndex.fb
   900385  thumbnail.png

FlatBuffers 表頭（前 12–16 bytes）：

noteBundle                     18000000 14003400 20000000 00001c00
index/ios/HandwritingIndex.fb  10000000 0c001400 13001200
index/ios/RecordingIndex.fb    10000000 0c001200 11001000

三個檔都是無 file_identifier 的 FlatBuffers root table。manifest.json 只有
appVersion，沒有 schema 版本欄位——所以格式判定要靠容器內的條目結構
（有無 noteBundle / Session.plist），不能靠 manifest.json。

已知可行的部分（不必等 parser）

assets/*.mp4 是未加密的標準 AAC，ffprobe 直接讀得到 duration，
unzip 拆出來即可用。所以「從新容器取回錄音」today 就做得到，
缺的是筆跡與時間軸——也就是 note-to-html 的互動重播本體。

一則實測筆記的兩段錄音：3600.02 秒與 1234.14 秒，皆 codec_name=aac。

Impact

• 只要使用者用的是現行 Notability，note-to-html / note-to-pdf 就完全不可用。
  CONVERSIONS.md 標示 Note (.note) → HTML ✅ implemented，對這些使用者是過期的承諾。
• 目前的錯誤訊息會讓人往「檔案壞了 / 拿錯檔」方向排錯，而不是「格式世代不符」。
• 影響面隨時間單調變大：新版本只會越來越多，舊 .note 只會越來越少。

Open questions（需要確認才好定範圍）

1. 現行 Notability 是否仍提供 .note 匯出？ 若分享選單裡還有舊格式，
   本 issue 降級為「錯誤訊息要講清楚 + 文件註明版本前提」；若已完全汰換，
   那就是真正的功能缺口。這題會實質改變優先級，應先回答再開工。
2. Notability 的 FlatBuffers schema 未公開，需要逆向。要不要做，取決於 (1)。
3. 若決定支援：是否先落地「只抽 assets/ 錄音 + thumbnail.png」的降級路徑，
   讓使用者至少拿得回音訊與預覽圖，筆跡重播留待 schema 逆向完成？

建議的分階段做法

階段	內容	成本
0	容器偵測 + 精確錯誤訊息（認出 noteBundle 就說「新版 .ntb，尚未支援」）；CONVERSIONS.md 註明支援的是舊格式	小
1	降級路徑：抽 assets/* 錄音與 thumbnail.png，不解析筆跡	中
2	逆向 FlatBuffers schema，完整支援筆跡 + 音訊同步重播	大

階段 0 不論 open question 的答案是什麼都值得做——現在的錯誤訊息本身就是誤導。

---

實測環境：macdoc 0.5.0、macOS 26.x、Notability 16.8.1 匯出檔。
測試檔為私人會議筆記，未附上；上方所有結構資訊皆為容器層 metadata，不含筆記內容。

Clarity Surface（idd-clarify run 2026-08-11T06:51:55Z）

Type	Source	Suggested canonical	Status
ambiguity	"Notability 的現行筆記容器是 .ntb"	本文對此的信心與下方 Open question 1（「需要確認」）不一致。「現行」是從單一匯出樣本推得，未驗證 .ntb 是唯一/預設格式，亦未確認 16.8.1 是最新版（該值來自 manifest.json 的 appVersion，即寫檔當下的 app 版本）。建議把 Problem 段改為「至少自 16.8.1 起，匯出得到的是 .ntb」	surfaced
missing-context	"Notability 的 FlatBuffers schema 未公開，需要逆向"	未查證是否已有社群逆向成果（如既有 .ntb parser / 公開 schema）。此點直接決定階段 2 的成本量級，開工前應先搜尋	surfaced

掃描依 terminology library（statistics/ML 領域）無 terminology 命中，屬預期——本 issue 是檔案格式領域。
上述兩列均為作者自身斷言的信心校準，非第三方用語問題。

---

Current Status

Phase: implemented
Last updated: 2026-08-13 by idd-all / spectra-apply

Key Decisions

• Phase 0 uses ZIP entry names only: Session.plist is legacy; otherwise noteBundle is modern FlatBuffers.
• Modern .ntb and renamed .note containers fail locally with one stable Traditional Chinese diagnostic.
• Legacy .note HTML/PDF conversion remains unchanged; full FlatBuffers parsing is not claimed.

Scope Changes

• Delivery intentionally selects the issue Expected fallback: precise unsupported-generation handling, not full .ntb conversion.

Blocking

• (none)

Tasks

• 1.1 Implement the Prove behavior with synthetic metadata-only archives test contract in Tests/MacDocCLITests/NotabilityContainerDetectionTests.swift: generate payload-free ZIP fixtures for .ntb and renamed .note, then verify the Modern Notability container rejection coverage scenarios are RED because the compiled CLI lacks the exact modern-generation diagnostic and no-output guarantee.
• 2.1 Implement Classify from normalized ZIP entry names without extracting payloads and Classify Notability container generation from ZIP entry metadata in Sources/MacDocCLI/NotabilityContainerDetector.swift, including legacy precedence, modern detection, unknown fallback, and a direct ZIPFoundation dependency in Package.swift; verify focused unit assertions classify synthetic entry sets and swift package describe --type json succeeds without changing the resolved ZIPFoundation revision.
• 2.2 Implement Gate both HTML and PDF note routes before converter construction and Reject modern FlatBuffers note conversion precisely and before output in Sources/MacDocCLI/MacDoc+Convert.swift; verify .note and .ntb HTML/PDF compiled cases emit the exact diagnostic, empty stdout, non-zero exit, and leave destinations absent while existing legacy note smoke tests remain green.
• [P] 3.1 Implement Qualify documentation rather than overstate support and State the Notability generation support boundary in README.md and CONVERSIONS.md; verify a documentation regression finds legacy plist-based .note, detected-but-not-supported modern .ntb, and an explicit statement that FlatBuffers replay is not implemented.
• 4.1 Run the complete phase-0 acceptance: focused Notability tests, existing Note HTML/PDF smoke tests, root swift test, spectra validate detect-notability-ntb-container, dependency and privacy checks, and git diff --check; record exact results and confirm no real Notability fixture or payload content is added.

Commits

• 6a5663b feat: detect unsupported Notability containers (note-to-html 不支援 Notability 現行的 .ntb 容器（FlatBuffers），只認舊的 plist-based .note #148)

[kiki830621]

Diagnosis

Type

feature（phase-0 compatibility boundary）

Root Cause / Analysis

目前 MacDoc.Convert 只接 .note → html/pdf，並直接交給遠端 NoteToHTML／NoteToPDF。底層 NoteCore.NoteParser 會解開 ZIP 後尋找舊格式的 Session.plist；找不到時一律回報「可能不是 Notability 筆記檔」。

Issue 已提供足夠、且不含私人內容的容器 metadata：新版匯出檔以 ZIP 包住 top-level noteBundle、version、manifest.json 與 FlatBuffers indexes。階段 0 可以只讀 ZIP entries 判斷世代，不需解析 noteBundle，也不需接觸私人 fixture。

Strategy

• 以 Spectra 固定 phase-0 契約：辨識 .ntb／含 noteBundle 的新版容器，精確 fail-loud；舊 .note 行為不變。
• 在 MacDocCLI 直接使用既有 resolver 已採用的 ZIPFoundation，只列 entry names、不解壓 payload。
• 先補 synthetic ZIP 的 compiled CLI RED：.ntb → html 與偽裝成 .note 的新版容器都必須回同一精確正體中文診斷，且不得建立 output。
• 更新 README／CONVERSIONS，將 ✅ 明確限定為 plist-based legacy .note，把 .ntb 標成 detected-but-not-supported。
• 跑 note package／CLI focused／root tests、Spectra validate、privacy scan與 diff-check。

Scope Boundary

本輪只交付 issue Expected 的替代分支：「若不支援新容器，錯誤訊息需明講偵測到新版 .ntb、目前只支援舊 .note」。不做 FlatBuffers schema 逆向、筆跡／時間軸解析、assets錄音抽取，也不聲稱已支援 Notability 16.8.1 的互動重播。

Conflict Class

C_shared_module_coord — 會修改 root Package.swift、MacDoc+Convert.swift 與 CONVERSIONS.md；使用獨立 idd/148-ntb-container-detection worktree，避免和其他 CLI／manifest issue碰撞。

Complexity

Spectra。雖然演算法小，但公開 CLI 錯誤契約、根 dependency、測試與兩份使用者文件分散在至少五個檔案，符合跨檔 hard gate。

Risks

• 只靠副檔名會漏掉 .ntb 被改名為 .note；因此判斷必須看 ZIP entries。
• 不得讀取或記錄 noteBundle、音訊、manifest內容；錯誤只提固定 entry名稱與格式世代。
• 容器不是 ZIP或 entries不符合新版形狀時，應保留既有 parser診斷，不可把所有損毀檔誤報成 .ntb。

Residue

完整 .ntb FlatBuffers schema、音訊降級匯出與互動重播仍需要公開／可分享 fixture、schema證據與另一次範圍決策；phase 0 不會掩蓋這個缺口。