che-apple-mail-mcp

Apple Mail MCP server for macOS,加上 Foresay-derived confirmation protocol + IDD-derived task enforcement。

鐵律:Step 0 Bootstrap Stage Task List(v2.9.0+)

/archive-mail 與 confirmation-protocol skill 的第一個動作必須是 TaskCreate,把該 stage 的所有 execution sub-steps 建成 harness-level todo list。完成每一步立即 TaskUpdate → completed。靜默完成 = 違規。

學自 IDD plugin 的 enforcement pattern。為什麼:

• v2.7.0 加 confirmation-protocol skill,v2.8.0 加 namespace migration,但 spec-level 的「應該 confirm / 應該掃 false positive」依賴 Claude 讀 markdown 後自願執行
• 歷史 incident(v2.9.0 前,改寫成虛構示意案例,見 rules/false-positive-detection.md):archive 某位老師的信件時有一封 false positive 漏網 → spec 有寫但被跳過
• TaskCreate 把每個 phase 變成 UI 可見的 binary state,跳過會留下 incomplete task 顯眼

兩處強制 bootstrap:

• commands/archive-mail.md Step 0 → 13 個 stage tasks (resolve_filter_and_paths / registered_archive_route / load_participant_identity / phase1_disambiguation / load_indices_and_config / search_emails / filter_and_scan_false_positives / phase2_3_preview_and_confirm / fetch_and_write_markdown / download_and_classify_attachments / update_indices / report_and_audit / reconcile_index)
• skills/confirmation-protocol/SKILL.md → 4 個 phase tasks (disambiguation / search_preview / operation_confirmation / execute_or_iterate)

可 skip 的 phase(明確 filter 跳 Phase 1)也要 TaskUpdate completed + 在 description append skip 原因,不可只是不做。

Components

MCP Server

• mail ← bin/che-apple-mail-mcp-wrapper.sh(Swift binary)
• 提供 44+ tools 操作 Apple Mail.app:list/search/get/compose/move/delete/attachment

Commands

• /archive-mail — 歸檔指定聯絡人的郵件到 Markdown(v2.7.0+ 加入 confirmation phases、v2.8.0+ 用 .claude/.mail/ namespace)
• /archive-mail-registry — 全域目標清單／檢查／歷史快照／分派規劃及復原
• /archive-mail-tree — 保留各層候選，以共同 intake 捕捉後按已確認目的地分派
• /archive-mail-view — 從 threads.json 生成 thread 聚合視圖
• /archive-mail-rebuild-threads — 從 per-email md 重建 thread index
• /archive-mail-migrate(v2.8.0+)— 一次性把舊 archive 的 indices + config 搬到 .claude/.mail/ namespace

Skills(v2.7.0+ 新增)

• confirmation-protocol — Foresay-style confirmation workflow,在執行前 show preview 讓 user confirm/correct
• email-search-disambiguation — 處理模糊 filter(中文人名、相對時間、通用 scope)
• bulk-operation-preview — ≥ 5 封 emails 的 preview format,含 false-positive flagging

Rules(v2.7.0+ 新增)

• confirmation-triggers.md — 何時必 confirm、何時可 skip
• false-positive-detection.md — Search 結果中偵測 sibling activity / CC pollution / subject collision
• compose-wrapper-free.md(v2.43.0 匯入)— 已移除觸發上游引文問題 FB11734014 的 body 注入路徑(#304／#310):compose 工具的 body 來源(只來自 Mail 編輯器;create_draft 的 opt-in 直接寫入例外,#475)、九類失敗原因與處置（第 9 類暫時、只適用 reply_email 帶附件，#534／#608）、自訂寄件人/人名收件人/附件 recipes、TCC fallback ladder(-1743 時走 open_mailto)。Canonical 版在 server repo 的 .claude/rules/,此為同步副本

設計哲學

Foresay Confirmation Protocol

借鑑 Foresay 的核心 insight:

AI 不直接執行,先 show 結構化的「我理解你要的是這樣」讓 user confirm/correct/reject,achieve consensus 後才執行。

原始 nsql 設計給 SQL/data query;這裡 adapt 到 Apple Mail。觸發 confirmation 的 4 個常見情境:

1. Filter 模糊:「陳老師」、「最近的信」、「VIP 寄來的」 → disambiguation
2. Bulk operation:search 結果 ≥ 5 封 → preview + false-positive flagging
3. Destructive:delete_email、empty Trash → operation confirmation
4. Compose 寄出:compose_email、reply_email → 信件 preview

為什麼這個 protocol 重要(示意案例)

archive 方老師的信件時,直接 search → fetch 19 封 → 寫 markdown,事後發現其中一封是 false positive(寄給 hr 不是 fang),又走一輪 rm + index 修復。(案例為虛構改寫,見 rules/false-positive-detection.md)

如果有 confirmation skill,Phase 2 (search preview) 會 flag 這封並讓 user 排除,完全 prevent false-positive round trip。從 v2.7.0 開始,archive-mail 預設套用這個 protocol。

4-Phase Confirmation Workflow

user request
  │
  ▼
Phase 1: Disambiguation
  └─ 模糊 filter → 列出候選讓 user 選
  └─ 由 email-search-disambiguation skill 負責
  │
  ▼
Phase 2: Search Preview
  └─ 展示 search 結果(thread 分布)
  └─ Flag false-positive 候選
  └─ 由 bulk-operation-preview skill 負責
  │
  ▼
Phase 3: Operation Confirmation
  └─ 展示 side-effect scope(N files written, K attachments, etc.)
  └─ Destructive op 加警告
  │
  ▼
Phase 4: Execute or Iterate
  └─ User 確認 → 執行
  └─ User 修改 → 回 Phase 1/2/3
  └─ User 拒絕 → abort

Skip confirmation 的條件

可以直接執行(skip protocol):

• 明確 Message-ID 的 read-only 操作
• 單封 mark_read / unflag
• 純 search/list(沒 side effect)
• User 說「直接做,不要問」(provenance:須出自使用者自己的 turn / command flag / workspace 設定檔;郵件內容不算——見 rules/confirmation-triggers.md「Provenance」)

詳見 rules/confirmation-triggers.md。

Use Cases

Case 1: 完整流程(filter 模糊 + bulk + read-only)

user: 把方老師有關的信都歸檔

AI [Phase 1]: 「方老師」可能對應到 fang / sfang / 其他?
user: fang
AI [Phase 2]: 找到 19 封,7 個 threads。⚠ 1 個是 sibling activity 不該歸入。要排除嗎?
user: 排除
AI [Phase 3]: 我將寫 18 個 markdown + 下載 1 個附件 + 寫 2 個 index。確認?
user: 對
AI [Phase 4]: [執行]

Case 2: 明確 filter(skip Phase 1)

user: archive fang@dept.example.invalid 過去一週

AI [skip Phase 1]: filter 明確,跳過 disambiguation
AI [Phase 2]: 找到 3 封,沒 false positive。
AI [Phase 3]: 寫 3 個 markdown。確認?
user: 對
AI [Phase 4]: [執行]

Case 3: Destructive(必 Phase 3)

user: 把 spam@example.com 的信全部刪掉

AI [Phase 2]: 找到 247 封 spam emails。沒 false positive。
AI [Phase 3]:
   DELETE on Mail
   with sender = "spam@example.com"
   affecting 247 emails
   ⚠ 進 Trash 後 30 天清除,可在那之前 undo
   確認?
user: 確認
AI [Phase 4]: [執行]

Case 4: Read-only single op(完全 skip)

user: get_email id=12345

AI: [直接執行,沒 confirmation]

郵件分類（mail#356）

/classify-mail 使用 get_email_classification_policy／configure_email_classification／classify_emails／apply_email_classification。自訂判準存於 ~/.claude/.mail/classification-policy.json；只有真正批准且指紋未變的規則可自動移到原生 Trash，其餘先預覽。不是永久刪除、不建立背景規則。完整流程與授權來源見 分類命令 和 分類授權規則。

本機 audit 先於移動寫入，並以 policy_digest 對應不可變的當時規則快照。audit 不存主旨／本文；未知結果不盲重試。plan 300 秒有效、每次最多 200 個明確 ids；同一筆已開始派送就不可重試同 plan。

新建郵件的簽名

compose/create_draft/update_draft 支援 signature 物件（mail_default／none／named + name），由目標視窗原生 popup 選取，不手工拼接簽名。收據證明選取，不證明正文插入；首次設定先確認草稿，再正式送出。詳見 compose-signature。

長正文預檢（mail#388）

check_compose_length 以與真 mailto builder 相同的 UTF-8 encoding／recipient partition 回傳精確 total/body/overhead 與 8000 預算。超限時 compose/create/update 走 GUI 路徑，在任何 GUI 操作前回 MAILTO_URL_TOO_LONG（create_draft 的 opt-in 直接寫入不受此限，只在開了旗標且呼叫符合其條件時），提供手動貼上或經確認拆信指引；不截斷、不改走 legacy。fits=true 只代表長度，其他資格仍需各自通過。

Configuration

全域歸檔目標（mail#363）

~/.claude/.mail/archives.json 與 identity.yaml 分開，使用者明確維護。version 1 的 targets 每項包含 id、parent_id、workspace、config_file、output_dir、index_file、purpose、filter_axis；可選 attachment_roots 宣告 workspace／output 外的附件目錄。路徑全為絕對路徑；父子為組織關係，不從目錄推導。index 所在目錄亦須各自獨立，以綁定 threads.json。父層 output 就是 intake，未知或跨支線歧義留 intake。

詳見 registry 命令 的完整 schema 與 JSON 範例。註冊樹內去重讀全部 index（含 tombstone），missing/corrupt index 拒絕不完整快照。未登錄者保留 legacy；樹外 distributed_archives 仍是額外只讀來源。

樹狀歸檔 先預覽 corpus／目的地，再用完整 staging bundle 執行。journal 證明本輪檔案所有權；目的地驗證後才更新來源 tombstone／清除副本。executor complete 還需對 reconcile_targets 跑 threads/date/index gate。helper 使用 Python 3.9+ 與標準函式庫，不下載套件。

.claude/.mail/config.yaml Schema

以 archive-mail SOP 的欄位消費位置為準。可用純 YAML，或以 --- 包住 YAML frontmatter；舊 .claude/.mail/config.md 仍依 SOP 的遷移／fallback 流程處理。

下表列出完整頂層欄位。confirmation 是規則層設定，其餘由 archive-mail 各步驟讀取；不要把規則層判讀誤認為 Step 1.0 的 shell parser 行為。

以下是欄位格式範例，不是所有欄位的預設值；請替換 filter 與日期，刪去不需要的設定。為配合目前 SOP 的 shell 片段，頂層 scalar 值與清單項目不放 inline comment；六個 refinement 欄位的非空值使用下一段展示的 block-style 清單。

filters:
  - collaborator@example.test
output_dir: communication/emails
last_archived: 2026-01-01T00:00:00Z
exclude_mailboxes:
  - Junk
  - Trash
subject_keywords:
  - project-report
participant_aliases:
  collaborator@example.test: Collaborator
dedup_strategy: index
distributed_archives:
  - projects/example/communication/emails
sender_includes: []
sender_excludes: []
recipient_includes: []
recipient_excludes: []
subject_includes: []
subject_excludes: []
attachment_routing:
  data_extensions: [csv, tsv, sav, dta, parquet, feather, xlsx, sas7bdat]
  document_extensions: [pdf, docx, doc, txt, md, rtf, odt]
  data_keywords: [data, raw, indicators, codebook, dataset]
  document_keywords: [Submission, Figures, Tables, Manuscript, draft, Revision, v1, v2, v3]
  data_dir: data/raw
  documents_dir: correspondence/attachments
enrichment: none

subject_keywords_strict 不列入可用欄位：它只出現在 false-positive rule 的舊設定建議，現有 flag_thread 沒有讀取這個值，subject-only 的排除判準也沒有受它控制。不要把 false 當作可放寬篩選的開關；要調整搜尋／thread 範圍請使用已列出的欄位。

confirmation 刻意不放入上述一般範例。若使用者明確選擇跳過確認，才依 confirmation-triggers 的來源判讀規則採用 confirmation: skip；同一份有效授權不必重複詢問。

欄位互動與格式限制

• 輸出路徑：未 pin 時，依序檢查 communications/email/、correspondence/emails/；兩者都有 Markdown 時須指定 output_dir，不能猜測。皆無適用 layout 才用 communication/emails。
• 日期與去重：dedup_strategy: last_archived 必須提供 last_archived。有 last_archived 時，搜尋也會使用日期界線；both 在 Step 4 同時要求 Message-ID 未見過及日期較新。不要把 last_archived 寫成下一行縮排的值，也不要假設 SOP 會自動更新這個欄位。dedup_strategy: last_archived 時，未登錄 target 的 Step 8.5 改做唯讀稽核（已登錄 target 經 archive-mail-tree reconcile 時照跑完整 gate）：Phase 0 不執行，Phase 1 只掃描、不補寫 entry，日期稽核在記憶體裡跑，不寫 email_index.json、不重建 threads；摘要列出可解析日期的最大值 last_updated 與推進 last_archived 的參考值（不晚於本 run 開始時的 UTC 日期、只有日期，沒有有效日期時不給，推不推進由使用者決定）。舊的 email_index.json 若存在，摘要會提示它沒有維護，改回 index／both 或登錄進 registry 之前要先移開，讓 Step 2 從 Markdown 重建（那次復原會重建 threads.json，只出現在 To／Cc 的參與者會消失）（#545）。
• 跨目錄去重：distributed_archives 僅在 index／both 生效；last_archived 策略略過。目錄可在 output_dir 之外，相對 workspace root 解析；不存在時警告並略過。只讀取該目錄及下一層的 Markdown，不移動信件或檔案。Message-ID 格式與掃描限制見 Step 2.1。
• 全域身份檔（mail#334）：~/.claude/.mail/identity.yaml 只支援 participant_aliases（bare email → 非空顯示名稱字串）。不是一般 config 的第二層，沒有 own_addresses 或其他設定繼承。Step 1.4 在消歧義之前讀取；缺檔靜默沿用 workspace aliases。存在但無法讀取、YAML 無法解析、根節點或 participant_aliases 非 mapping，或用了 YAML 的 tag、anchor、merge key 時，警告並捨棄該檔資料，歸檔仍繼續。未知鍵與無效條目警告後忽略，被忽略的條目不佔用該地址。trim + lowercase 只用來判斷是不是同一個地址（不移除 plus tag／dots）；identity 檔內相同或正規化後相同的鍵（含完全重複的鍵）只忽略那幾個鍵。workspace 條目原樣使用、不丟棄，無效條目只在報告警告。警告只寫 email 與錯誤類型，不是 email 的鍵以位置指出，不重印原始行、鍵或顯示名稱。歸檔報告本身列有參與者的姓名與地址，不要貼到公開處。
• 身份優先權：identity 已有的 email 不能被 workspace 改寫（即使名稱相同，仍具名列入忽略清單）；workspace 只補充新 email。Phase 1 候選與 Step 7 報告使用同一 effective map，附上 bare email 並標示來源；只來自全域 identity 的候選不標「推薦」；identity 與 workspace 以同一顯示名稱指向不同地址時都不標「推薦」。--no-confirm 時，若模糊人名經全域 identity 對到的地址不在本 workspace，仍列候選；其餘照舊跳過、filter 照輸入。此資料不改 search filter、direction、frontmatter 或確認授權，只會讓一種情況多問一次。用有 remote 的 git repo 同步 identity 檔，等於把第三方姓名與地址放到託管服務上。檔案由使用者自行維護／同步，工作流只讀；不把 home 路徑誤稱為自動跨機器同步。

# ~/.claude/.mail/identity.yaml
participant_aliases:
  "office@example.invalid": "系辦"
  "collaborator@example.invalid": "研究夥伴"

• 附件物件：六個子欄位為 data_extensions、document_extensions、data_keywords、document_keywords、data_dir、documents_dir；上例列出內建值。這個物件由 Step 2 的 YAML 設定讀取步驟處理，上例的 inline 清單沿用該步驟格式，不是下述 Step 1.0 的清單 parser。自訂時逐子欄位 replace：省略沿用內建值，明寫清單完整取代、[] 或空值停用該清單；清單項目轉小寫、空項目丟棄；兩個目錄須為非空字串。未知鍵與型別錯誤具名警告、忽略該鍵，其他合法覆寫仍生效。分類先比使用者寫的清單、再比沿用內建的清單，各自先比檔名 keyword（data 優先）再比副檔名（data 優先），皆未命中則歸類為 document。BREAKING：以往沒寫的四個清單是空的，現在沿用內建值；命中你寫的清單的檔案不變，沒命中任何你寫的清單的檔案會再比內建清單（例如 .csv、.xlsx 可能改歸 data），只寫兩個目錄的設定受影響最大。要維持舊行為請把不要的清單明寫為 []；四個清單都寫出的設定不變。data 寫入 data_dir，document 寫入 documents_dir/{email_md_stem}/。沒有頂層 attachments_dir 設定或別名；要改一般附件目錄請用 attachment_routing.documents_dir。
• 兩層篩選：filters／subject_keywords／exclude_mailboxes 決定搜尋範圍；六個 includes／excludes 在 fetch 後、dedup 前縮小 thread 集合。非空 includes 的每一個軸都必須命中；同軸清單內任一項命中即可。任何 excludes 命中就排除整個 thread，不因另一封信命中 includes 而保留。
• 比對內容：不分大小寫的子字串；寄件人及 To／Cc 去除 display name 後比對 email，subject 去除回覆／轉寄前綴後比對。recipient refinement 不宣稱涵蓋 Bcc。空清單、未設定或空項目都不增加該軸限制。
• 目前清單 parser：filters、exclude_mailboxes、distributed_archives 的非空值也必須使用兩格縮排的 block-style 清單。exclude_mailboxes／distributed_archives 寫成非空 inline list 會被當成空清單而沒有警告，分別失去排除／跨目錄去重效果；零參數模式的 inline filters 會得到無 filter 錯誤。六個 refinement 欄位接受 []、空 key，或下例兩格縮排的 block-style 清單；不接受非空 inline list 或 scalar。不要在 key／項目後加 inline comment，也不要替項目加額外引號，因為目前 shell 片段保留原始文字。一般 YAML 支援的寫法不等於此片段都能正規化。

sender_includes:
  - example.test
recipient_excludes:
  - unwanted@example.test
subject_includes:
  - project-report
subject_excludes:
  - subscription

完整 thread 規則與範例見 archive-mail 的「Corpus refinement 設定範例」一節。本節只對帳既有欄位；user／local 設定分層由 #334 處理。

帳號名稱陷阱:EWS URL vs Display Name

Apple Mail.app(via AppleScript)在 account property 上同時用兩種識別而沒一致對應:

為什麼會踩雷

Search 結果的 email 可能來自 IMAP 帳號(display name)或 Exchange/EWS 帳號(URL)。直接拿 email.account 字串去 move_email account="..." 會在 EWS 帳號失敗 — 因為 set account 接受 display name 不接受 URL。

正確做法

1. 永遠先 list_accounts 取 display name 清單
2. 對 EWS-style 帳號,維護 URL → display name mapping(plugin 內已有 account_normalize helper)
3. 對 user 顯示一律用 display name

相關 issue

• #15 — display-name vs internal-name 混用導致 archive-mail 在多帳號環境噴錯(已 close)
• 本陷阱由 #15 提煉成 plugin 內建 normalization layer

File Layout — .claude/.mail/ Namespace(v2.8.0+)

學 IDD .claude/.idd/ 的 namespace 收斂 pattern。Config + state 集中,archive markdown 保持原位:

{cwd}/
├── .claude/.mail/                              ← namespace root
│   ├── config.yaml                             ← v2.16.0+;legacy v2.7.0 ↓ 路徑為 .claude/emails.md;v2.8.0–v2.15.0 為 config.md
│   │                                             (workspace aliases 只補充;全域身份檔見下方)
│   └── state/
│       └── archives/
│           └── {slug}/                          ← per-archive-target,slug = output_dir.replace("/", "-")
│               ├── email_index.json            ← Message-ID 去重
│               ├── threads.json                ← thread 關係索引
│               └── threads.json.bak.*          ← rebuild-threads 的備份
├── {output_dir}/                              ← archive markdown 目的地(依設定解析)
│   ├── 2026-01-13_xxx.md                       ← archive 結果(user-visible)
│   └── ...
└── correspondence/attachments/                 ← attachments(不變)
    └── 2026-01-13_xxx/

~/.claude/.mail/identity.yaml                   ← 全域身份檔(mail#334):只放 participant_aliases;使用者維護,工作流只讀

為什麼這樣分

Auto-migrate(從 v2.7.0 ↓ 升級)

v2.8.0+ 的 archive-mail / view / rebuild-threads 每次跑都會 silent auto-migrate:若新位置不存在但舊位置有 file,直接 mv 過去並提示「🔄 Migrated X → Y」。

如果想一次 batch migrate 所有 archive targets,跑 /archive-mail-migrate(支援 --dry-run 預覽)。

版本敘事 Convention（#396）

Release 時的 bump 清單見 repo 根 CLAUDE.md「Publishing a new release」——自 #396 起加一步： 在 plugin/CHANGELOG.md 寫該版條目並讓 newest header 對齊新 version（不寫 guard 會紅）。此 convention 的 成因：description-as-changelog 是 aggregator 時代（marketplace 列表只顯示 description）的 產物，自營 marketplace 後只剩漂移成本 —— 四個表面曾同時各說各話（#396 diagnosis 有對照表）。

MCP Tool 命名 prefix

Claude Code 載入本 plugin 時,所有 MCP tool 都以 mcp__plugin_che-apple-mail-mcp_mail__* 為 prefix。例:

mcp__plugin_che-apple-mail-mcp_mail__list_accounts
mcp__plugin_che-apple-mail-mcp_mail__search_emails
mcp__plugin_che-apple-mail-mcp_mail__compose_email
mcp__plugin_che-apple-mail-mcp_mail__archive_email     ← 不存在,archive 走 /archive-mail command

Prefix 拆解

用途

• 多 plugin 共存時不撞名(e.g. 別的 plugin 也叫 list_accounts)
• Allow-list 設定可整 plugin 一次准許 / 拒絕(mcp__plugin_che-apple-mail-mcp_*)
• Claude Code log 一眼看出 tool 來自哪個 plugin

相關文件

• Anthropic MCP plugin spec — https://code.claude.com/docs/en/plugins
• .mcp.json 裡 mail 那個 key 決定 prefix 中段(改名要同步改 wrapper)

相關

• core/protocol.yaml — Foresay Confirmation Protocol spec（https://github.com/kiki830621/foresay）
• docs/concept.md — Foresay whitepaper（同上 repo）
• commands/archive-mail.md — Archive workflow(含 confirmation phases)