Lilith Emails

🚀 莉莉絲郵件系統

莉莉絲郵件系統結合了Gmail同步守護進程和莉莉絲代理工具，可實現語義化郵件搜索，具備隱私感知分類和個人身份信息（PII）清理功能。

🚀 快速開始

1. 數據庫（共享的PostgreSQL）

本項目使用一個共享的PostgreSQL服務器。此應用的數據庫名稱為：lilith_emails。

確保共享的PostgreSQL（帶有pgvector）正在運行。首先克隆lilith-compose項目。

2. 運行遷移

uv run alembic upgrade head

3. 添加Gmail賬戶

從Google Cloud Console下載OAuth客戶端密鑰，然後執行以下命令：

uv run python main.py add-account path/to/client_secrets.json

4. 同步（僅下載）

uv run python main.py sync 1

日誌會顯示進度：已獲取的頁面、已存儲的郵件消息以及到目前為止的總數。

5. 轉換（分類 + 清理 + 嵌入）

在同步完成後運行此步驟，以從存儲的數據中生成privacy_tier、body_redacted和多級嵌入（主題、正文或塊）。如果更改了模型或邏輯，可隨時重新運行（無需重新下載）。

uv run python main.py transform 1

清理轉換命令添加的所有派生列：

uv run python main.py reset-transform 1

6. 運行同步守護進程（Pub/Sub Webhook）

uv run python main.py serve

當守護進程收到Gmail Pub/Sub推送時，它會自動為該賬戶運行增量同步，然後進行轉換。

沒有公共URL（本地開發）：使用拉取而不是推送。創建一個拉取訂閱，在.env中設置PUBSUB_SUBSCRIPTION，然後運行：

gcloud auth application-default login
uv run python main.py watch 1
# 在另一個終端中，輪詢通知（與Webhook的同步+轉換相同）：
uv run python main.py pull

創建拉取訂閱（與主題在同一項目中）：
gcloud pubsub subscriptions create lilith-emails-pull --topic=gmail-topic --project=lilithsync

有公共URL：使用推送訂閱（端點 = 你的公共/webhook/gmail URL），並使用uv run python main.py serve運行守護進程。註冊一次監視：uv run python main.py watch <account_id>（需要在.env中設置GOOGLE_CLOUD_PROJECT和PUBSUB_TOPIC）。

如果監視返回403：授予Gmail向你的主題發佈的權限：

gcloud pubsub topics add-iam-policy-binding gmail-topic \
  --member="serviceAccount:gmail-api-push@system.gserviceaccount.com" \
  --role="roles/pubsub.publisher" \
  --project=lilithsync

本地測試Webhook

你可以通過POST一個模擬的Pub/Sub有效負載來觸發相同的路徑，而無需依賴Gmail。首先運行一次完整同步，使賬戶有last_history_id，然後啟動守護進程併發送：

# 在另一個終端中啟動守護進程：uv run python main.py serve --port 8000

# 替換YOUR_EMAIL和HISTORY_ID（例如從數據庫中獲取：email_accounts.last_history_id）
# 跨平臺（任何操作系統）：
python3 -c "
import base64, json, urllib.request
d = base64.b64encode(json.dumps({'emailAddress':'YOUR_EMAIL','historyId':'HISTORY_ID'}).encode()).decode()
urllib.request.urlopen(urllib.request.Request('http://localhost:8000/webhook/gmail', data=json.dumps({'message':{'data':d}}).encode(), headers={'Content-Type':'application/json'}, method='POST'))
print('OK')
"

或者使用curl（Linux：使用base64 -w0；macOS：使用base64）：

B64=$(echo -n '{"emailAddress":"YOUR_EMAIL","historyId":"HISTORY_ID"}' | base64)
curl -s -X POST http://localhost:8000/webhook/gmail -H "Content-Type: application/json" -d "{\"message\":{\"data\":\"$B64\"}}"

守護進程將為該賬戶運行增量同步，然後進行轉換。使用get-email或MCP工具驗證新的或更新的行。

📦 配置

環境變量（.env或shell）：

轉換使用capabilities.json：在轉換之前運行uv run python main.py capabilities，以便該文件存在幷包含embedding.max_tokens、vllm.model_id、spacy_api.available和fasttext_langdetect.available。轉換沒有環境變量回退機制。已設置transform_completed_at的郵件將被跳過，除非使用--force（會提示確認）；如果轉換在運行過程中失敗，這些郵件將在下一次重試。

📦 MCP服務器（代理工具）

莉莉絲郵件MCP服務器可公開你轉換後的Gmail數據。

uv run mcp
uv run mcp --transport streamable-http --port 6201

MCP工具

所有響應都採用外部隱私策略：敏感內容會被屏蔽，個人內容會經過清理後顯示。