archive-mail SOP Step 5 遷移至 batch_export_emails_markdown 批次路徑（#232 SOP 側缺口）

[kiki830621]

Problem

/archive-mail SOP 的 Step 5「生成 Markdown」主路徑仍是 per-email get_email(format='text') 逐封 fetch + client-side transcription（commands/archive-mail.md Step 0 task 描述與 Step 5 本文皆然），而 binary 端的 server-side 批次匯出工具已成熟且自 binary v2.18.0 起以 batch_export_emails_markdown 為 canonical 名（che-apple-mail-mcp#233；舊名 export_emails_markdown 為 deprecated alias）。

這正是 che-apple-mail-mcp#232 事故的 SOP 側缺口：#232 的 Proposed Solution 第 1 項「Step 5 大批量走批次路徑（強制/預設）」在該 issue 關閉時只落地了 binary 側（rename + 命名 discoverability，經 #233 出貨）；SOP 側的 Step 5 遷移至今未動。SOP 文字甚至完全沒有出現任何 export 工具名（grep 零命中）— AI 執行者照 Step 5 逐封抓是文件指示的預期行為，不是偏差。

Proposed Solution（依 #232 原案）

1. Step 5 在待歸檔清單 ≥ N 封（建議 ≥ 5，對齊既有 confirmation gate）時 SHALL 改用 batch_export_emails_markdown（一次呼叫、per-email manifest、skip_message_ids_path dedup、manifest message_id 可直接 reconcile INDEX_FILE）；per-email get_email 迴圈降為 fallback。
2. SOP 需說明「按 direction 拆批」慣例（工具用單一 mailbox 參數標 direction，mixed corpus 拆收/寄兩批；見 #232 Considerations）。
3. Step 5.5 附件流程與 batch 匯出的 opts.include_attachments 的分工要明文（batch 匯出可含附件；classify 到 data/documents 的既有分流邏輯如何銜接需設計）。
4. frontmatter 契約對齊：工具輸出 6-field frozen frontmatter + body_type/in_reply_to；SOP 現行 frontmatter 欄位（thread_key/direction）是 client-side 加值，遷移後由 manifest 後處理補寫或保留 client-side 步驟，需設計決定。

Context

• che-apple-mail-mcp#232（事故 + 原案；已關，binary 側完成）
• che-apple-mail-mcp#233（rename 出貨，binary v2.18.0 / plugin v2.27.0）
• 實測成本：63 封歸檔逐封 get_email vs 兩次 batch 呼叫

---

✅ Verified（PR #114 @ frozen ada402d，tag idd-107-verified）

Step 5 主路徑遷移至 batch_export_emails_markdown（Step 5.0），per-email 降為 Step 5.1 fallback（<5 / enriched / batch 失敗）。shell v2.32.0（binary 不動 v2.19.0）。

6-AI verify 兩輪。R1（dc849ff）四 verifier 全 FAIL，DA REQUEST-CHANGES + 3 REQUIRED——攔下三個真實缺陷：

1. direction 按 recipe provenance 分區的資料正確性 bug（3 verifier 收斂）：3b/3c 是跨匣 subject 搜尋、帶使用者自己的寄出信，全歸「received 批」→ 寄出信誤標 direction: received（subject_keywords/zero-arg 模式每封寄出信都誤標）。→ 改按每封信自己的 mailbox 真分區（批 B = matchesSpecial(id.mailbox, Sent)；批 A = 其餘 − uncertain），批 B 傳字面 "Sent"（locale-robust）。
2. filename-authority bug（Codex BLOCKER）：opts.filenames 只是請求名（工具對 override branch 也 uniquify、seed 自 on-disk）→ downstream 一律以 manifest.written_path 為準。
3. thread_key superset 碎裂（binary-cap FAIL）：工具去 回覆:/回复: + case-insensitive 的 superset，SOP 舊規則窄 → batch/fallback 同 thread 拿不同 thread_key。→ SOP thread_key rule + Step 3 regex 對齊 binary superset；sender 記 lowercased、date 記 offset-preserving。

R2 re-verify（ada402d）：綜合 lens PASS（3 REQUIRED 全落地、regex 與 binary 完全一致、對 #112 Step 8b 安全）+ DA APPROVE。post-verify polish fa47894（2 cheap doc-precision）。Master report。

已知 follow-up（非本次）：SOP 的 Layer-2 corpus-refinement subject matcher 仍用 pre-Fix-3 窄前綴集（不同 code path，屬 archive-mail-corpus-refinement spec）。

狀態：停在 verified。merge 順序 #108 → #111 → #113 → #114（archive-mail 塔）；plugins#110 stack 在本 PR 上；close 由維護者決定。

[kiki830621]

Diagnosis

Complexity: Plan-tier（SOP 主路徑重構 + 多個設計決策；純 doc，無 binary/test）

關鍵查證 — 推翻原案 point 4 的前提

原案 point 4 假設「工具輸出 6-field frozen frontmatter，SOP 現行 thread_key/direction 是 client-side 加值，遷移後需後處理補寫」。核對 binary 後推翻：

EmailMarkdownRenderer.render（EmailMarkdownRenderer.swift:50-76）寫出的 frozen frontmatter 正是 SOP simple template 的同 6 欄位：

欄位	工具來源	與 SOP simple template
message_id	resolved RFC 5322	相同
thread_key	stripReplyPrefixes(subject)	同規則（Re:/RE:/Fwd:/FW:/转发:/轉寄:/回覆:/回复: 去前綴）
in_reply_to	header（無則空字串）	相同
date	ISO 8601 原始 offset（#244）	相同
sender	bareEmail（剝 display name）	相同
direction	caller 經 mailbox 參數導出	相同（received/sent）

body header 為 Subject/From/To/Cc(有才印)/Date —— 是 SOP simple template（Subject/From/To/Date）的 superset。所以 simple template 路徑無 frontmatter reconciliation gap，遷移接近 drop-in。

設計決策（實作將落地為 SOP prose）

#	決策	理由
1 門檻	待歸檔 ≥ 5（對齊既有 confirmation gate）走 batch；per-email get_email 迴圈降為 fallback（enriched template / batch 失敗 / < 5）	大批量才值得；小批量 per-email 延遲可接受
2 direction 拆批	工具用單一 mailbox 參數標 direction。mixed corpus 拆兩次呼叫：received ids（不帶 Sent mailbox → received）+ sent ids（帶 Sent 實名 → sent）	直接複用 #109 已分離的 Sent corpus（recipe (2) 的 scoped Sent 搜尋）
3 附件	batch 呼叫不帶 opts.include_attachments（只匯出 body）；附件仍走 client-side Step 5.5	工具 include_attachments 只按副檔名分流（data ext → data/、其餘 → attachments//），缺 SOP 的 keyword classify、inline cid: 圖片、cross-reference——是 SOP Step 5.5 的粗粒度子集，不可取代
4 enriched template	batch 路徑僅 simple template；enrichment: summary+todos 設定時走 per-email 路徑（AI 摘要/待辦無法伺服器端產）	誠實邊界：工具不產 enrichment；50 個歷史歸檔全 simple，batch 是 common-case 優化
5 filename 慣例	傳 opts.filenames per-id map，用 SOP 現行 filename 規則（保留 Re-- 前綴、不合併連續 dash、-N 碰撞後綴）算出	工具預設 filename（slug(threadKey), ExportEmailsMarkdown.swift:212/241）吃已 strip Re: 的 threadKey 且合併連續 dash → Re: x 變 x 而非 Re--x，會偏離 50 檔命名慣例。filename 只需 (id,date,subject)（Step 4.5 preview 已有），無需 body fetch
6 dedup	Step 4 的 Message-ID dedup（對 INDEX_FILE）維持在 batch 前；傳給工具的 ids 已是新信。skip_message_ids_path 為選配 belt-and-suspenders（防 index/corpus drift）	不改既有 dedup 語意

Conflict Class: C_shared_module_coord（與 archive-mail 塔同檔 archive-mail.md）

故 stack 在塔頂 idd/112（PR #113）上，塔延伸 #108→#111→#113→#107，避開 fork conflict。#110 再 stack 在 #107 上。

Refs

• che-apple-mail-mcp#232（事故 + 原案，binary 側已完成）、#233（rename 出貨）、#193（工具設計）、plugins#109（Sent scoping 複用）