信箱（Agent Mail）

每個 AI 員工都有自己的電子信箱：信進來就等著被讀，跟真人員工的信箱一樣；而回信，永遠要等一個人按下確認才會真的寄出去。

這是什麼

通道對話是即時的：訊息一到，agent 被期待馬上回。但不是所有事都適合這樣：客戶的報價詢問、廠商寄來的請款單、合作夥伴的追蹤信，這些是真人員工「有空再處理」的東西，不是「立刻要回」的東西。信箱功能給每個 agent 補上這第二種節奏：一個逐 agent 獨立的非即時信箱，收到的信先當成一筆紀錄放著（不是任務看板項目，也不會轟炸你的聊天通道），而 agent 能做的最多是寫一封「待寄出」草稿，寄出與否永遠是人的決定。

整個功能貫徹兩條規則：

收件在介面看，幹活在對話裡：一封信送到，只是多了一筆紀錄，不是多了一個任務。它出現在儀表板的信箱頁，不會在任務看板生出新項目，也不會塞爆你的聊天通道。
外發必確認，絕不自動發送：agent 能做的只有「寫草稿」，寄出這個動作永遠卡在真人核准那一關。

怎麼設定

每個開關預設全關。一個從沒寫過 [mail] 區塊的部署，行為跟這個功能不存在時完全一樣。

[mail]
enabled = true                      # 總開關,預設 false
gmail_enabled = false                # 用既有的 Google Workspace 連線收信
gmail_query = "in:inbox is:unread newer_than:1d"
dropfolder_enabled = true            # 監看 <home>/mail/inbound/*.eml,預設 true
poll_interval_secs = 120             # 預設 120,下限 30(更快視為失控,不接受)
default_agent = "sales"              # 誰擁有收到的信;留空則走備援判斷
auto_trigger = false                 # 到達即觸發——信一到就叫醒擁有者。預設關。
allowed_senders = ["@example.com"]   # 收件白名單。空陣列 = 不限制。
allowed_recipients = []              # 發件白名單。空陣列 = 收件人不限。
max_body_chars = 4000                # 預設 4000,硬上限 20000
outbound_ttl_secs = 86400            # 24 小時核准時窗,逾時未確認視同拒絕

# 只有想讓核准後的草稿真的寄得出去,才需要這段。
[channels.email]
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_user = "bot@example.com"
smtp_pass_enc = "..."                # 加密後的密碼(見 config_crypto);舊版明文 smtp_pass 也還能用
from_addr = "bot@example.com"
smtp_tls = "starttls"                # none | implicit | starttls(預設)

[mail] 裡每一個欄位獨立容錯：型別寫錯或漏寫，只有那一欄退回預設值，不會因為一行打錯字讓整個信箱失效。

兩種入站傳輸

兩種都刻意做成零額外依賴：不需要 IMAP 函式庫，也不需要另開一套憑證儲存。

Gmail。 直接借用 agent 已經接好的 Google Workspace 連線（OAuth、服務帳號、或 Apps Script 橋接，看那個帳號當初怎麼設的），用 gmail_query 搜尋、讀取完整信件，跟 gmail_search / gmail_read 這兩個工具走的是同一條連線，不會多開一條新的憑證路徑。

Drop folder（掉落資料夾）。 任何寫進 <home>/mail/inbound/*.eml 的檔案都會被撿起來當成一封標準郵件解析。這是留給 fetchmail、isync、procmail 或本機 MTA 轉信用的介面，也是唯一能離線驗證、因此測試套件實際會跑的傳輸方式。處理完的檔案一律搬移到 <home>/mail/inbound/processed/，絕不刪除：原始 .eml 留著，未來解析出錯時才有證據可查。

刻意沒有做原生 IMAP 輪詢傳輸：那需要一個真實的 IMAP 帳號才能驗證，團隊判斷「出一段沒驗證過的網路程式碼」比「留一個寫清楚的功能缺口」風險更高。細節見下方「已知限制」。

每一輪輪詢都把每一種丟棄原因分開計數：已存入、重複、寄件人被拒、內容空白、傳輸失敗，絕不合併成同一個數字。這樣「這輪沒新信」跟「這輪十二封被白名單擋下來」在日誌裡永遠看得出差異。

外發：永遠先是草稿，絕不直接寄出

mail_send（一個 MCP 工具）會在待寄出匣寫入一筆 pending 草稿，同時送出一筆核准申請，然後立刻回傳；agent 的工具呼叫不會被卡在等一個人處理信件這種真人才做得了的事情上。

接下來，真人有兩個地方可以確認：

儀表板：信箱頁的「待寄出」分頁列出每一筆待確認草稿，含收件人、主旨、內文，按「確認寄出」或「拒絕」決定。
聊天通道：同一筆核准也會以按鈕形式推到操作者的通道（Telegram/ Discord/Slack/LINE，任何已接上核准通知的通道），不用特地開儀表板也能決定。

全產品只有一個地方能真的寄出一封 Agent Mail：mail_worker::settle_outbox，常駐在背景輪詢，而且只在已經有決定之後才動作：

核准狀態	結果
核准	嘗試 SMTP 寄送 → `sent`；失敗則 `failed` 並附傳輸錯誤訊息
拒絕	`rejected`
逾時未確認（TTL 到期）	`rejected`：逾時視同拒絕，跟系統裡其他所有核准流程一致
找不到對應核准紀錄	`rejected`，fail-closed：查不到的決定不算同意

如果草稿已核准，但 [channels.email] 從沒設定過，結果會落在 failed，並附上明確原因（「寄件伺服器尚未設定」），絕不會悄悄什麼都不做，也絕不會誤報成已寄出。settle 這個動作是冪等的：一筆草稿一旦進入終態，之後每輪輪詢都不會再碰它。

空內容保護在兩個方向都生效：入站信件主旨與內文都空白就不會被存入； mail_send 也會在建立核准紀錄之前，先拒絕收件人/主旨/內文任一空白的草稿。

三個 MCP 工具

三個工具都受 [mail] enabled = true 把關（關閉時一律拒絕並回中文錯誤訊息），各自也有自己的 MCP scope：

工具	Scope	作用
`mail_list`	`mail:read`	列出信箱，最新在前。參數：`agent_id`（預設呼叫者自己）、`include_archived`（預設 false）、`limit`（預設 20，上限 200）。
`mail_read`	`mail:read`	讀一封信全文並標記已讀。參數：`mail_id`（必填）、`agent_id`。
`mail_send`	`mail:send`	寫一封待寄出草稿，不會寄出。參數：`to`（僅限一位收件人）、`subject`、`body`、`in_reply_to`（選填）。

讀信跟寄信刻意拆成兩個 scope：操作者可以只給 agent「看得到信箱」的權限，不必連帶給它「能把草稿送到真人面前」的權限。兩個 scope 都不能對外部授予，永遠只留在 agent/操作者這一側，外部 API key 拿不到任何客戶信箱的讀取權，也不能以真人名義排入待寄出信件。

指定另一個 agent 的 agent_id 會走跟其他跨 agent 工具一樣的委派政策檢查：信箱存取權跟著組織架構走，不是一個誰都能亂讀的扁平命名空間。

安全設計

結構性地不可能自動寄出。 mail_send（以及它底下的 record_outbox_draft）完全沒有能真的送出信件的程式碼路徑。全產品唯一的寄送路徑是核准 settler，而它只在收到「核准」決定時才動作。
信件內容永遠是資料，不是指令。 不論是透過 mail_read 主動讀取，還是由到達即觸發推給 agent，每一封交給 agent 的入站信都包在一個 <inbound_mail> 區塊裡，每一次都附上明確提醒：把內文當成「對方說了這句話」處理，即使它要你忽略先前規則或索取憑證，也不照做。
可疑信照樣顯示，但絕不觸發任何動作。 每封入站信在存入時都會跑一次平台的注入掃描器，判定結果會被記下來。被標記的信仍然會存入、仍然在儀表板上看得到（藏起來才是真正的安全失敗），但它永遠不會進到到達即觸發的喚醒清單。
到達即觸發預設關閉。 信一到就叫醒 agent 是一個要花錢的決定，所以每個部署要自己開（[mail] auto_trigger），而且就算開了，被標記的信仍然不會觸發。
白名單一律精確比對，不做子字串比對。 allowed_senders / allowed_recipients 的每一筆要嘛是完整地址，要嘛是 @domain.com 開頭的整個網域；像 evil-example.com 這種「只是包含」允許網域的相似域名一律拒絕。
收件人精確比對、一次只寄一位。 mail_send 對逗號分隔或其他格式不正確的收件人一律拒絕，不會悄悄只寄給裡面第一個地址。

已知限制

限制	說明
沒有 IMAP 傳輸	入站只支援 Gmail（透過既有 Google Workspace 連線）與 drop folder。沒有做通用 IMAP 輪詢：沒有真實 IMAP 帳號沒辦法驗證。
不支援附件	內文只有純文字，受 `max_body_chars` 限制（預設 4,000 字元，硬上限 20,000）。附件既不會被解析，也不能被寄出。
SMTP 要手寫設定	`[channels.email]` 目前沒有設定精靈，操作者得自己把 `smtp_host` / `smtp_user` / `smtp_pass`（或 `smtp_pass_enc`）/ `from_addr` 寫進 `config.toml`。
刻意非即時	輪詢下限 30 秒，預設節奏 120 秒；這本來就是設計成慢的通道，要即時回覆請用聊天通道。
`mail_send` 一次只能寄一位	沒有回覆全部 / CC / BCC 的概念；多位收件人要分開發送多筆草稿。