[English](./README.md) | [繁體中文](./README.zh-TW.md)

# Project Aegis (AgentPay)

Project Aegis 是專為 Agentic AI（如 OpenClaw、NemoClaw、Claude Code、OpenHands）設計的**支付護欄與一次性交易協議**。它能讓 AI Agent 安全地處理金融交易，同時避免人類信用卡被無限制地暴露於風險之中。

## 1. 問題背景
當 Agentic AI 在自動化工作流程中遭遇付費牆（如網域註冊、API 額度、運算資源擴展）時，通常被迫停下來等待人類介入。然而，直接將實體信用卡提供給 Agent 會引發「信任危機」：幻覺（hallucination）或無限迴圈可能導致信用卡被刷爆。

## 2. 雙軌架構 (Dual Architecture)

Project Aegis 基於「雙軌架構」的願景設計，能從開源的本地實驗，輕易擴展至企業級的 AI 生產管線。

### 1. 駭客版 (BYOC + DOM Injection)
專為 OpenClaw、NemoClaw 等開源框架設計。Agent **永遠不會**拿到真實的信用卡號，只會看到經過遮罩的版本（如 `****-4242`）。當 Agent 成功導航到最後結帳頁面時，Aegis 的 `AegisBrowserInjector` 會透過 Chrome DevTools Protocol (CDP) 直接連線至活躍的 Chromium 瀏覽器，穿透並遍歷所有跨網域 Iframe（如 Stripe Elements），精準將真實的信用卡憑證注入底層的 DOM 表單元素。此機制能提供 **100% 免疫 Prompt Injection** 與幻覺提取的防護。讓你安心在本地環境使用自己的信用卡 (Bring Your Own Card, BYOC)。

### 2. 企業版 (Stripe Issuing)
更廣泛 Agentic SaaS 生態系的「北極星」。Aegis 證明了它具備真實世界所需的企業級擴展能力，能完美介接合規的金融基礎設施。這非常適合想要建立「Agentic Visa」服務的平台，能透過 Stripe API 替雲端的 AI 艦隊動態發行真實、拋棄式的虛擬信用卡 (VCC)。

---

## 3. 生態系定位：Aegis + 瀏覽器 Agent = 所向無敵

現代 Agentic 工作流程需要兩種互補的能力。Aegis 負責其中之一，並把它做到極致。

### 🎯 Aegis 是什麼 — 以及不是什麼

**Aegis 是 Agent 的財務大腦與保險箱。** 它負責：
- ✅ 評估某筆購買是否*應該*發生（語意護欄審核）
- ✅ 執行硬性預算限制（每日上限、單筆上限）
- ✅ 核發一次性虛擬卡，確保真實信用卡資訊絕不外洩
- ✅ 完整保存每一筆支付嘗試的稽核紀錄

**Aegis 不做以下事情：**
- ❌ 瀏覽網站或操作 DOM 元素
- ❌ 破解 CAPTCHA 或繞過反機器人機制
- ❌ 代替 Agent 填表或點擊「送出」

那些是瀏覽器 Agent 的工作。

### 🤝 協作交接：Aegis 如何與瀏覽器 Agent 協同運作

真正的威力來自 Aegis 與瀏覽器自動化 Agent（如 OpenHands、browser-use、Skyvern）的配合。這是一種清晰的職責分工：

```
1. [瀏覽器 Agent]  導航至網站，抓取商品資訊，到達結帳頁面。
        │
        │  （遇到付費牆 / 支付表單）
        ▼
2. [瀏覽器 Agent → Aegis MCP]  呼叫 request_virtual_card(amount, vendor, reasoning)
        │
        │  （Aegis 評估：預算OK？供應商已核准？沒有幻覺？）
        ▼
3. [Aegis]  核發一次性虛擬卡（Stripe 模式）或模擬卡（開發模式）
            向 Agent 回傳遮罩後的卡號。完整卡號僅透過
            可信任的本地執行環境注入 — 絕不進入 LLM 的上下文。
        │
        ▼
4. [瀏覽器 Agent]  使用核准的憑證完成結帳表單填寫。
        │
        ▼
5. [The Vault]  Dashboard 記錄交易。虛擬卡立即銷毀。
```

### 🌐 支援的瀏覽器 Agent 整合

| 瀏覽器 Agent | 整合方式 | 參考文件 |
|---|---|---|
| **OpenHands** | MCP Tool Call | [快速上手 §4](#4-快速上手--openclaw--nemoclaw--claude-code--openhands) |
| **OpenClaw + browser-use** | MCP Tool Call | [快速上手 §4](#4-快速上手--openclaw--nemoclaw--claude-code--openhands) |
| **NemoClaw（沙箱）** | 沙箱內 MCP Tool Call | [快速上手 §4](#4-快速上手--openclaw--nemoclaw--claude-code--openhands) |
| **自訂 Playwright / Selenium** | Python SDK `AegisClient` | [整合指南](./docs/INTEGRATION_GUIDE.zh-TW.md) |
| **Skyvern / browser-use** | Python SDK 中間層 | [整合指南](./docs/INTEGRATION_GUIDE.zh-TW.md) |

> 完整程式碼範例（包含 Playwright 注入與 System Prompt 模板）請參閱 **[docs/INTEGRATION_GUIDE.zh-TW.md](./docs/INTEGRATION_GUIDE.zh-TW.md)**。

---

## 4. 安裝

```bash
# 僅核心功能（關鍵字護欄 + mock provider，零外部依賴）
pip install aegis-pay

# 加裝 LLM 語意護欄（支援 OpenAI、Ollama、vLLM、OpenRouter）
pip install aegis-pay[llm]

# 加裝 Stripe 虛擬卡發行
pip install aegis-pay[stripe]

# 加裝 LangChain 整合
pip install aegis-pay[langchain]

# 完整安裝（所有功能）
pip install aegis-pay[all]
```

## 5. 快速上手 — OpenClaw / NemoClaw / Claude Code / OpenHands

如果你使用 OpenClaw、NemoClaw、Claude Code、OpenHands 或任何支援 MCP 的 Agentic 框架，你可以在 2 分鐘內啟動 Aegis：

### 步驟一：安裝並啟動 MCP Server

```bash
# 複製儲存庫
git clone https://github.com/TPEmist/Project-Aegis.git
cd Project-Aegis

# 安裝依賴
uv sync --all-extras

# 啟動 MCP server
uv run python -m aegis.mcp_server
```

### 步驟二：連接你的 Agent

**OpenClaw：**
```bash
# 在 OpenClaw 中註冊 Aegis 為 MCP 工具
openclaw mcp add aegis -- uv run python -m aegis.mcp_server

# 或手動加入 OpenClaw MCP 設定檔（~/.openclaw/mcp_servers.json）
```
```json
{
  "aegis": {
    "command": "uv",
    "args": ["run", "python", "-m", "aegis.mcp_server"],
    "cwd": "/path/to/Project-Aegis",
    "env": {
      "AEGIS_ALLOWED_CATEGORIES": "[\"aws\", \"cloudflare\", \"openai\"]",
      "AEGIS_MAX_PER_TX": "100.0",
      "AEGIS_MAX_DAILY": "500.0"
    }
  }
}
```

**NemoClaw（NVIDIA 安全沙箱）：**

NemoClaw 將 OpenClaw agent 包裝在安全沙箱中。在你的 NemoClaw 沙箱內設定 Aegis：

```bash
# 連接到你的 NemoClaw 沙箱
nemoclaw my-assistant connect

# 在沙箱內註冊 Aegis MCP server
openclaw mcp add aegis -- uv run python -m aegis.mcp_server
```

> **注意：** NemoClaw 限制檔案存取權限。請確保 Project-Aegis 複製到 `/sandbox/` 內，以便 agent 能存取。`aegis_state.db` 會建立在沙箱的可寫入目錄中。

**Claude Code：**
```bash
claude mcp add aegis -- uv run python -m aegis.mcp_server
```

**OpenHands：** 加入你的 MCP 設定：
```json
{
  "mcpServers": {
    "aegis": {
      "command": "uv",
      "args": ["run", "python", "-m", "aegis.mcp_server"],
      "cwd": "/path/to/Project-Aegis"
    }
  }
}
```

### 步驟三：設定你的安全策略（環境變數）

```bash
export AEGIS_ALLOWED_CATEGORIES='["aws", "cloudflare", "openai", "github"]'
export AEGIS_MAX_PER_TX=100.0        # 單筆交易上限 $100
export AEGIS_MAX_DAILY=500.0         # 每日總預算上限 $500
export AEGIS_BLOCK_LOOPS=true        # 阻擋幻覺 / 重試迴圈
# 可選：export AEGIS_STRIPE_KEY=sk_live_...（Stripe 設定請見 §8）
```

### 步驟四：開始使用

你的 Agent 現在可以使用 `request_virtual_card` 工具。當它遇到付費牆時：

```
Agent：「我需要從 AWS 購買 $15 的 API 金鑰才能繼續。」
[Tool Call] request_virtual_card(amount=15.0, vendor="AWS", reasoning="Need API key for deployment")
[Aegis] ✅ 請求已核准。卡片已核發：****4242，有效期：12/25，金額：15.0
Agent：「購買成功，繼續工作流程。」
```

如果 Agent 產生幻覺或試圖超支：
```
Agent：「讓我再試一次購買運算資源……上次又失敗了。」
[Tool Call] request_virtual_card(amount=50.0, vendor="AWS", reasoning="failed again, retry loop")
[Aegis] ❌ 請求被拒絕。原因：偵測到幻覺或無限迴圈
```

---

## 6. 核心元件

### 🛡️ The Vault（金庫）
基於 **Streamlit** 與 **SQLite** (`aegis_state.db`) 的本地視覺化控制台。The Vault 讓人類可以：
- 即時監控所有已核發的 Seal 與 Agent 消費活動。
- 監控全域預算使用率。
- 審查來自語意護欄的拒絕紀錄。

### 📜 The Seal（封印）
內建執行機制的虛擬一次性支付憑證：
- **每日預算硬限制**：自動阻擋任何會超過預設每日消費上限的請求。
- **用後即焚攔截**：確保虛擬卡一旦被使用後立即失效，防止重播攻擊或未授權的重複扣款。

### 🧠 語意護欄（Semantic Guardrails）
Aegis 提供兩種意圖評估模式，防止 Agent 浪費資金：
1. **快速關鍵字攔截**（預設）：使用 `GuardrailEngine` 即時阻擋包含迴圈或幻覺相關關鍵字的請求（如「retry」、「failed again」、「ignore previous」）。零依賴、零成本。
2. **LLM 語意護欄引擎**：由 `LLMGuardrailEngine` 驅動，對 Agent 的推理進行深度語意分析，檢測無關購買或邏輯不一致。支援**任何 OpenAI 相容端點** — 包括透過 Ollama/vLLM 的本地模型，或 OpenAI、OpenRouter 等雲端服務。

## 7. 安全聲明
安全性是 Aegis 的第一優先。SDK **預設遮罩卡號**（如 `****-****-****-4242`），在回傳授權結果給 Agent 時不會暴露完整卡號。這能防止敏感支付資訊洩漏到 Agent 的對話紀錄、模型上下文視窗或持久化日誌中，確保只有執行環境能處理原始憑證。

## 8. The Vault Dashboard（監控面板）

The Vault 是你即時監控所有 Agent 支付活動的控制台。

### 啟動 Dashboard

```bash
cd Project-Aegis
uv run streamlit run dashboard/app.py
# Dashboard 會開啟在 http://localhost:8501
```

### Dashboard 版面配置

| 區域 | 說明 |
|---|---|
| **側邊欄：Max Daily Budget 滑桿** | 調整顯示用的預算上限（不影響後端策略 — 後端策略透過環境變數或 SDK 設定） |
| **Today's Spending** | 今日 Agent 累計消費金額 |
| **Remaining Budget** | 今日剩餘預算 |
| **Budget Utilization** | 預算使用率進度條 |
| **💳 Issued Seals & Activity** | 所有支付嘗試（核准 + 拒絕）的完整表格，含 seal ID、金額、供應商、狀態與時間戳 |
| **🚫 Rejected Summary** | 僅顯示被拒絕/阻擋的嘗試，方便快速審查 |

### 使用提示
- 點擊側邊欄的 **Refresh Data** 以獲取最新活動資料。
- Dashboard 讀取的是 `aegis_state.db` — 與 SDK 寫入的是同一個資料庫。同時運行兩者即可即時監控。
- 表格中的每一列對應 Agent 的一次 `request_virtual_card` 呼叫。

---

## 9. Python SDK 快速入門

只需幾行程式碼即可將 Aegis 整合到你的 Python 或 LangChain 工作流程：

```python
from aegis.client import AegisClient
from aegis.providers.stripe_mock import MockStripeProvider
from aegis.core.models import GuardrailPolicy

# 定義你的安全策略
policy = GuardrailPolicy(
    allowed_categories=["API", "Cloud", "SaaS"], 
    max_amount_per_tx=50.0, 
    max_daily_budget=200.0,
    block_hallucination_loops=True
)

# 使用僅關鍵字護欄初始化客戶端（預設）
client = AegisClient(
    provider=MockStripeProvider(), 
    policy=policy,
    db_path="aegis_state.db"
)

# 或使用本地模型的 LLM 護欄（例如 Ollama）
from aegis.engine.llm_guardrails import LLMGuardrailEngine

llm_engine = LLMGuardrailEngine(
    base_url="http://localhost:11434/v1",  # Ollama 端點
    model="llama3.2",
    use_json_mode=False
)
client = AegisClient(
    provider=MockStripeProvider(),
    policy=policy,
    engine=llm_engine
)

# 搭配 LangChain Tool 使用
from aegis.tools.langchain import AegisPaymentTool
tool = AegisPaymentTool(client=client, agent_id="agent-01")
```

### 支援的 LLM 供應商

| 供應商 | `base_url` | `model` |
|---|---|---|
| OpenAI（預設） | *（不需要）* | `gpt-4o-mini` |
| Ollama（本地） | `http://localhost:11434/v1` | `llama3.2` |
| vLLM / LM Studio | `http://localhost:8000/v1` | 你的模型名稱 |
| OpenRouter | `https://openrouter.ai/api/v1` | `anthropic/claude-3-haiku` |
| 任何 OpenAI 相容端點 | 你的端點 URL | 你的模型名稱 |

---

## 10. 支付供應商：Stripe vs Mock

### 不使用 Stripe（預設 — Mock Provider）

預設情況下，Aegis 使用 `MockStripeProvider` 來模擬虛擬卡發行。適用於：
- **開發與測試** — 不涉及真實金錢
- **展示與評估** — 無需任何 API 金鑰即可體驗完整流程
- **黑客松** — 幾分鐘內就能跑出可運作的原型

Mock 卡在 Aegis 系統內完全可用（預算追蹤、用後即焚、護欄全部正常運作），但它們不是真實的支付工具。

```python
from aegis.providers.stripe_mock import MockStripeProvider

client = AegisClient(
    provider=MockStripeProvider(),  # 不需要 API 金鑰
    policy=policy
)
```

### 使用真實的 Stripe Issuing

若要透過 [Stripe Issuing](https://stripe.com/issuing) 核發**真實的虛擬信用卡**：

**前置條件：**
1. 具備已啟用 [Issuing](https://stripe.com/issuing) 的 Stripe 帳號（需申請審核通過）
2. 你的 Stripe 密鑰（`sk_live_...` 或 `sk_test_...`）

**方法 A：透過環境變數（適用 MCP Server）**
```bash
export AEGIS_STRIPE_KEY=sk_live_your_stripe_key_here
uv run python -m aegis.mcp_server
# MCP server 會自動使用 StripeIssuingProvider
```

**方法 B：透過 Python SDK**
```python
from aegis.providers.stripe_real import StripeIssuingProvider

client = AegisClient(
    provider=StripeIssuingProvider(api_key="sk_live_your_stripe_key_here"),
    policy=policy
)
```

**Stripe Issuing 的運作方式：**
- 建立真實的 Stripe 持卡人（`Aegis Agent`）
- 核發虛擬卡，消費限額與核准金額相符
- 僅回傳遮罩後的卡片資訊（末 4 碼）給 Agent
- 所有 Stripe 錯誤都會被捕獲並以拒絕原因回傳

> **備註：** Stripe Issuing 是 Stripe 的進階產品，需要申請通過。對於大多數開發與展示場景，Mock provider 已經足夠。
