Bremen
/
emma-hermes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emma-hermes/docs/gateway-resilience/gateway-functional-contract.md

13 KiB
Raw Blame History

Gateway Functional Contract

目標：把 Hermes gateway 在 identity 綁定、長任務交付、LINE quota fallback、email 檔案交付、shared drive 下載工作流 的可接受行為定義成明確契約，未來更新或重構時可直接逐條核對。

實際程式碼再確認

本文件依下列 live 模組與測試整理：

  • gateway/user_verification.py
  • gateway/run.py
  • gateway/platforms/base.py
  • plugins/platforms/line/adapter.py
  • plugins/platforms/email/adapter.py
  • hermes_cli/managed_downloads.py
  • hermes_cli/web_server.py
  • tests/gateway/test_line_plugin.py
  • tests/gateway/test_email.py
  • tests/gateway/test_approval_prompt_redaction.py
  • tests/gateway/test_display_config.py
  • tests/hermes_cli/test_managed_downloads.py
  • tests/hermes_cli/test_web_verification_admin.py
  • tests/gateway/test_principal_profile_routing_phase1.py
  • tests/gateway/test_verified_email_handoff_guard_helpers.py

這份文件只記錄目前已在程式或測試中有明確落點的行為，不把尚未實作的理想狀態假裝成既有功能。

1. Principal / verified email 綁定契約

1.1 authoritative source

  • verified email 的 live 來源是 GatewayUserStore。
  • 主要查詢入口：GatewayUserStore.get_verified_email_for_source(source)。
  • 系統不得只靠對話上下文、記憶摘要、舊 prompt、舊 session 欄位決定要寄到哪個 email。

1.2 handoff 前必做 live confirm

  • 任何 系統主動 把結果寄到使用者綁定信箱的流程，在寄出前都必須重新確認：
    • active source 的綁定 email
    • 與即將寄送的 target email
    • 必須完全一致
  • 目前這條 hard guard 已有明確函式：
    • GatewayUserStore.bound_email_matches_source(...)
    • LINE 側經 LineAdapter._verified_email_target_if_bound(...) 使用

1.3 例外規則

  • 若是 使用者明確指定其他 email，可用 explicit_user_requested=True 略過 bound-email equality check。
  • 這個例外只適用使用者明講的目的地，不適用系統自行 fallback 或自動推論。

1.4 不可接受行為

  • 把別的 principal 的 verified email 當成目前 source 的綁定信箱
  • 用 stale session state / context compression 結果直接寄信
  • 無 live confirm 就直接把 LINE / Telegram / OpenWebUI 的結果轉寄到 email

1.5 principal context 與 profile routing

  • verified source 除了 email handoff guard，還會產生 principal context：
    • GatewayUserStore.get_principal_context(source)
    • gateway/principal_profiles.py
  • verified principal 若啟用 principal_profile_routing，應穩定解析到同一 principal profile。
  • 不可因 update / restart 導致同一 principal 突然丟失 profile mapping，否則會讓該 principal 的後續權限、工具、長任務脈絡一起漂移。

2. LINE 長任務契約

2.1 pending / postback state machine

  • LINE 慢回覆流程使用 RequestCache 狀態機：
    • PENDING
    • READY
    • DELIVERED
    • ERROR
  • show_response postback 只在該 cache 路徑中取回結果。
  • 若任務還沒完成，show_response 必須回 pending 狀態，不得假裝 final 已送達。

2.2 pending button 的語意

  • pending button 是「稍後取回答案」機制，不是 final delivery 本身。
  • 若 final 結果已轉到 email surface，後續 postback replay 必須保留「已改寄 email」事實，不能回 generic delivered copy。

2.3 長任務 heartbeat

  • gateway 允許 long-running heartbeat，但 LINE 預設應是 安靜、泛化、對客版。
  • tests/gateway/test_display_config.py 已明確固定：
    • tool_progress == off
    • busy_ack_detail == false
    • long_running_notifications == generic
  • 不應把 raw tool names、iteration counter、工程英文直接丟給 LINE 使用者，除非明確 opt-in。

2.4 non_conversational 與 bypass

  • system busy-acks / approval / update 類通知必須以 non_conversational metadata 保護，不可被誤收進最終交付內容。
  • heartbeat 與 background/system notices 不得誤變成使用者的 final email。

2.5 不可接受行為

  • heartbeat 冒充 final answer
  • 查看答案 重播時遺失 fallback surface 狀態
  • 長任務提示持續噴工程實作細節，讓使用者以為系統異常

3. LINE quota fallback → email 契約

3.1 fallback 觸發條件

  • LINE push quota / push send 失敗時，應嘗試改走 verified email fallback。
  • fallback payload 必須明確標記為：
    • email_fallback_pending
    • 或 email_fallback

3.2 pending 與 final 要分開

  • pending 階段：
    • 可寄一次「仍在處理中，完成後會寄到驗證 email」通知
    • 應避免重複寄一堆同樣 pending 通知
  • final 階段：
    • 應寄出完整內容
    • 並明確告知已改由 email 交付

3.3 fallback ownership transfer

  • 一旦 final answer 已由 email fallback 接手，後續 post-stream 附件交付也必須沿用同一 email surface。
  • 不得又回頭走 LINE 原生檔案送出，造成：
    • 使用者已收到 email，卻又看到 LINE 附件送失敗
    • 或 delivery state 自相矛盾

3.4 replay contract

  • DELIVERED 狀態若 payload 為 email_fallback，replay / postback 必須重播 fallback notice，而不是 generic Already replied 類文字。

3.5 不可接受行為

  • LINE quota 滿了卻靜默失敗
  • fallback email 只寄文字，不帶原本該帶的檔案資訊或下載連結
  • 使用者之後查詢結果時，看不到「其實已改寄 email」這個事實

4. Email 檔案交付契約

4.1 MIME attachment contract

  • 若有附件且未超限：
    • email 應為 multipart
    • 要附真正 MIME attachment
    • 檔名要保留副檔名
    • Content-Disposition / Content-Type filename 參數要正確
  • tests/gateway/test_email.py 已固定這個契約

4.2 HTML + plain text contract

  • email 不只 plain text，也要帶 HTML body
  • 裸 URL 在 HTML 中應轉成可點擊的 <a href=...>

4.3 large attachment contract

  • 若附件總大小超過 email 限制：
    • 不應狂寄多封
    • 應改成單封通知 + 下載連結
    • payload 應保留：
      • attachments_omitted_reason = size_limit
      • omitted_filenames
      • download_links

4.4 download link contract

  • 對客下載連結應優先使用 managed downloads 正式網域
  • 目前由：
    • hermes_cli/managed_downloads.py
    • hermes_cli/web_server.py 的 /downloads/{token}
  • token 必須可 resolve，且 route 必須真的能回檔案
  • tests/hermes_cli/test_managed_downloads.py 已固定：
    • URL shape
    • route 可下載
    • Content-Disposition 帶原始副檔名

4.5 不可接受行為

  • 說有附件，實際沒有 MIME attachment
  • 附件有帶出但沒有副檔名
  • 下載連結指到錯誤網域或重啟後失效 token
  • 附件太大寄失敗後，沒有自動切成 link-only

5. Approval / 對客通知契約

5.1 approval 文案

  • approval fallback 文案應為對客繁中，不應把 raw command / security scan 原文直接外露。
  • 需要保留「可批准 / 拒絕」操作語意，但不洩漏敏感內容。

5.2 approval redaction seam

  • _redact_approval_command(...) 是 approval prompt 的硬性 secret-egress boundary。
  • chat platform path 與 SSE/API path 都必須在送出前實際使用 redacted command。
  • tests/gateway/test_approval_prompt_redaction.py 已釘住這條契約。

6. Shared drive workflow 契約

6.1 查找與選檔契約

  • shared drive 對話式工作流目前落在：
    • ~/.hermes/scripts/shared_drive_index_query.py
    • ~/.hermes/scripts/shared_drive_lookup.py
    • ~/.hermes/scripts/shared_drive_chat_workflow.py
  • search 必須回傳可對話使用的候選清單，且每個候選都帶 file_id。
  • 若命中資料夾，children <folder_file_id> 必須能展開子檔案清單，供使用者最多選 10 檔。

6.2 打包與敏感檔契約

  • bundle --file-ids ... --requester <email> 必須：
    • 以 file_id 解析實際檔案
    • 先複製到本機 staging
    • 產生 24h managed download link
  • 若命中個資 / 財務或無法可靠判讀內容，必須自動改走加密 zip，並保留第二通道密碼通知資訊。

6.3 驗證契約

  • bundle 結果必須帶 verification 欄位。
  • 成功判準以 真實 GET 為準，不以 HEAD 為準。
  • 不可把 urllib / Cloudflare 1010 這類 bot-like 驗證誤判直接當成下載路徑壞掉。

6.4 不可接受行為

  • search 找得到候選，但沒有 file_id，導致無法進入選檔/打包流程
  • children 展開不到資料夾內容，卻沒說明是 index 或 parent mapping 問題
  • 敏感檔仍走未加密原檔
  • 連結其實可用，卻因 HEAD/urllib 驗證誤判為壞掉

7. 額度與權限治理契約

6.1 governance store 是 live source of truth

  • principal、external identity、quota policy、model policy、dashboard role、admin audit log 的 authoritative store 都在 GatewayUserStore / gateway/user_verification.py。
  • schema 至少包含：
    • principals
    • external_identities
    • identity_enforcement
    • quota_policies
    • model_policies
    • dashboard_roles
    • principal_usage_daily
    • admin_audit_logs

6.2 dashboard role contract

  • dashboard verification/admin 角色目前分三級：
    • viewer
    • operator
    • admin
  • 權限邏輯由 hermes_cli/web_server.py::_require_verification_role(...) 控制。
  • 在 gated auth 模式下：
    • viewer：可讀 identities / principals / audit / quota / model / usage
    • operator：可 force-bind、unbind、block、unblock、resend verification、寫 quota/model policy
    • admin：可管理 dashboard role 本身
  • 在 loopback / 非 auth_required 模式下，server 目前視為 admin；這是便利行為，不是未來所有部署都該仰賴的安全模型。

6.3 quota policy contract

  • quota policy 目前已落地的資料欄位是：
    • daily_message_limit
    • daily_token_limit
    • notes
  • principal usage 目前已落地的統計欄位是：
    • message_count
    • input_tokens
    • output_tokens
    • total_tokens
    • last_model
  • gateway/run.py 在對話完成後會呼叫 GatewayUserStore.record_usage_for_source(...) 寫入 usage。

6.4 quota 的目前邊界

  • 目前 repo 內已明確存在的是：
    • quota policy CRUD
    • usage record / usage list
    • API / admin 測試 round-trip
  • 目前這一版文件 不把尚未在 live code 看到的硬性 runtime deny / throttle 假裝成已完整存在。
  • 換句話說：目前 governance 比較像「可觀測 + 可設定 + 可對帳」，不是已全面接管所有 gateway runtime 拒絕邏輯。

6.5 model policy contract

  • 每個 principal 可有：
    • allowed_models
    • default_model
  • 這些資料目前已可經 admin API round-trip 保存與查詢。
  • 若未來要主張「特定 principal 只能用指定模型」，必須再補 runtime enforcement 驗證；沒有測到前，不可把它寫成既成事實。

6.6 admin audit contract

  • 任何人工治理動作至少應留下 audit：
    • force bind
    • unbind
    • block / unblock
    • role assignment
    • quota / model policy 變更（若後續擴充，應一併補 audit）
  • 目前已確認 force_bind_identity 等身份治理動作可經 /api/admin/verification/audit 查回。

6.7 不可接受行為

  • principal 還在，但 quota / model policy / role 因 update 被洗掉或查不到
  • dashboard 可看 identities，卻看不到 usage / quota 對帳
  • 系統把「有 quota policy 紀錄」誤當成「runtime 一定已 enforce」

7. 目前管理平台功能契約（current admin surface）

7.1 已確認存在的管理後台能力

依 hermes_cli/web_server.py 與 tests/hermes_cli/test_web_verification_admin.py，目前至少已有這些 admin API：

  • GET /api/admin/verification/role
  • GET/POST /api/admin/verification/roles
  • GET /api/admin/verification/identities
  • GET /api/admin/verification/principals
  • POST /api/admin/verification/force-bind
  • POST /api/admin/verification/unbind
  • POST /api/admin/verification/block
  • POST /api/admin/verification/unblock
  • POST /api/admin/verification/resend
  • GET /api/admin/verification/audit
  • GET/POST /api/admin/quota-policies
  • GET/POST /api/admin/model-policies
  • GET /api/admin/principal-usage

7.2 這代表「目前管理平台」最少能做什麼

  • 查誰綁了哪個平台 identity
  • 查哪些 identities 被綁到同一 principal
  • 人工 force-bind / unbind / block / unblock
  • resend verification email
  • 指派 dashboard role
  • 設 quota / model policy
  • 查每日 principal usage
  • 查 admin audit log

7.3 目前不要過度聲稱的部分

  • 我這次沒在 live code 裡看到一個已完成、明確對應上述所有治理 API 的前端 SPA 頁面證據。
  • 所以目前比較穩的說法是：
    • 治理後台後端能力已存在並有測試覆蓋
    • 前端顯示/操作面是否完整暴露全部能力，仍需額外做 UI 對照驗證
  • 這可以避免未來有人誤以為「API 有 = UI 一定完整可用」。

8. 這份契約如何維護

每次修改以下任一區塊，都要同步檢查本文件是否要更新：

  • gateway/user_verification.py
  • gateway/run.py
  • gateway/platforms/base.py
  • plugins/platforms/line/adapter.py
  • plugins/platforms/email/adapter.py
  • hermes_cli/managed_downloads.py
  • hermes_cli/web_server.py
  • 對應 tests

若改動造成契約變更，應同時更新：

  1. 本文件
  2. gateway-state-and-sequence.md
  3. gateway-regression-matrix.md
  4. 對應 regression tests