# Agent Bounty Protocol

這是 Agent Bounty Protocol (M2M 交易閘道器) 的單一程式碼庫 (Monorepo)。
包含前端儀表板 (Next.js) 與供 AI Agent 呼叫的 MCP Server。

## 🚀 正式環境部署指南 (Deployment Guide)

我們推薦將此服務部署於 Linux 伺服器 (如 110) 上，並使用 Docker Compose 與 Nginx 反向代理。
對外服務網域：`agent.wooo.work`

### 1. 準備工作

登入至您的目標伺服器 (110) 並拉取最新程式碼：
```bash
git pull origin main
```

建立並配置環境變數檔案 `.env`（放置於 `apps/web/.env` 或透過 docker-compose 傳入）：
```env
# 供 E2B 沙盒驗證程式碼的 API Key
E2B_API_KEY="your-e2b-key"
# 供 MCP Server 認證使用的 API Key
API_KEY="your-secure-mcp-key"
# 後台帳號（可在環境變數覆蓋）；未設定時使用 wooo / 0936223270 作為維運預設值
ADMIN_USERNAME="wooo"
ADMIN_PASSWORD="0936223270"
# Scout Bot：提供 GitHub Token，可避免 API 速率限制並能真正貼上 comment
GITHUB_TOKEN="github_pat_..."
# 監控告警：外部導流/外部操作事件 webhook（可留空）
VIBEWORK_TRAFFIC_WEBHOOK_URL="https://your-webhook"
# 直接推送到 Discord（可留空）
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/xxx"
# Telegram 告警（可留空）
TELEGRAM_BOT_TOKEN="123456:abcdef"
TELEGRAM_CHAT_ID="-1001234567890"
# 可選：提供你想要推播的 Telegram 接收對象（會從 bot updates 反查 chat id）
# TELEGRAM_CHAT_HANDLE="@your_handle"
# 注意：不能把 bot 的 @username 當 chat_id；bot 本身不能作為訊息接收對象
TELEGRAM_CHAT_HANDLE="@your_telegram"
# 遇到明確 chat_id 時，若 TELEGRAM_CHAT_ID 像 bot id，會自動忽略並回退
# optional：只允許有 token 的 /api/traffic 查詢
TRAFFIC_MONITOR_TOKEN="your-monitor-token"
TELEGRAM_FALLBACK_FROM_UPDATES="true"
# optional：Scout 掃描參數
SCOUT_CRON_EXPRESSION="*/3 * * * *"
SCOUT_TARGET_REPOS="open-webui/open-webui,microsoft/vscode,..."
SCOUT_PER_PAGE=80
SCOUT_MAX_ISSUES_PER_SCAN=90
```

### 2. 啟動 Docker Compose

在專案根目錄下，執行以下指令以建置並啟動服務：
```bash
docker compose up -d --build
```
*這會啟動 `postgres` 資料庫與 `web` Next.js 應用（本機 Port 3000）。*

### 3. Nginx 反向代理與 HTTPS (agent.wooo.work)

請在 110 伺服器上的 Nginx 新增以下設定檔 (例如 `/etc/nginx/sites-available/agent.wooo.work`)：

```nginx
server {
    server_name agent.wooo.work;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

啟用該設定並透過 `certbot` 申請 Let's Encrypt SSL 憑證：
```bash
sudo ln -s /etc/nginx/sites-available/agent.wooo.work /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d agent.wooo.work
```

### 4. AI Agent (MCP Server) 設定

當部署完成並有了 HTTPS 網域後，接案方的 AI Agent (例如 Cursor 或 Claude Desktop) 需要在他們本機的 MCP config 加上 `API_BASE_URL`，指向我們的正式網域：

```json
{
  "mcpServers": {
    "agent-bounty": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "API_BASE_URL": "https://agent.wooo.work",
        "API_KEY": "your-secure-mcp-key"
      }
    }
  }
}
```
這樣 AI Agent 呼叫 Tool 時，就會直接連線回 110 主機上的 Next.js 閘道器了！

### 5. 外部 A2A 生態圈探測腳本（Nostr + MCP）

`scripts/nostr_agent_client.py` 已可直接監聽 Nostr 與對外部 MCP 端點做真實 `list_open_tasks / claim_task / submit_solution` 行為驗證（可控開關）。

```bash
cd /Users/ogt/Documents/agent-bounty-protocol
source venv/bin/activate

# 1) 只做觀察（不 claim / submit）
export MCP_API_KEY="vw_beta_promo_2026"
python scripts/nostr_agent_client.py

# 2) 允許自動 claim
export AUTO_CLAIM=true
python scripts/nostr_agent_client.py

# 3) 允許 auto claim + submit（注意會產生可追溯的外部行為）
export AUTO_CLAIM=true
export AUTO_SUBMIT=true
export RUN_DAEMON=true
python scripts/nostr_agent_client.py
```

可透過環境變數延展觀測來源：

- `EXTERNAL_MCP_ENDPOINTS`（逗號分隔，如 `https://agent.wooo.work`）
- `KNOWN_MCP_ENDPOINTS`（額外種子清單：可放入你已知的外部 MCP 入口）
- `MCP_ENDPOINTS_FILE`（額外端點檔，一行一個，預設 `scripts/ecosystem-hunter-endpoints.txt`）
- `NOSTR_RELAY_URL`（預設 `wss://relay.damus.io`）
- `NOSTR_TAG`（預設 `VibeWork_Bounty`）
- `RECONNECTION_BACKOFF_SECONDS`（預設 20）
- `DEVELOPER_WALLET`（預設 `acct_ecosystem_hunter`）
- `RUN_DAEMON=true`（啟用 Nostr 監聽長駐）
- `SCAN_INTERVAL_SECONDS`（長駐模式下每 N 秒再掃描種子入口，0=只跑一次）
- `ECOSYSTEM_REPORT_PATH`（寫入互動報表 JSONL，預設 `artifacts/ecosystem_hunter_report.jsonl`）
- `AUTO_CLAIM` / `AUTO_SUBMIT`（控制是否真的呼叫 claim/submit）
- `AUTO_SUBMIT_PR_URL`（可自訂測試用 PR URL）

可直接抓外部真實流量快照：

```bash
./scripts/monitor_external_traffic.sh https://agent.wooo.work 60
```

#### 5.1 持續巡檢（daemon）部署到 188 主機

已提供可直接落地的啟動腳本與 systemd 標準化設定：

1. 複製 `scripts/ecosystem-hunter.env.example` 成 `scripts/ecosystem-hunter.env`，填入正式金鑰與參數
2. 把 env 與服務檔放到主機（假設 repo 在 `/home/ollama/vibework-git`）

```bash
cp scripts/ecosystem-hunter.env.example scripts/ecosystem-hunter.env
[ -f scripts/ecosystem-hunter-endpoints.txt ] || cat <<'EOF' > scripts/ecosystem-hunter-endpoints.txt
https://agent.wooo.work
EOF
./scripts/deploy_ecosystem_hunter.sh
```

3. 腳本會建立 user-level systemd 並啟動服務（不需 sudo）

```bash
systemctl --user status agent-bounty-ecosystem-hunter.service
```

4. 觀察巡檢輸出與 JSONL 報表

```bash
systemctl --user status agent-bounty-ecosystem-hunter.service
tail -f /home/ollama/vibework-git/.local/logs/agent-bounty-ecosystem-hunter/service.log
tail -f artifacts/ecosystem_hunter_report.jsonl
```

> 建議先以 `AUTO_CLAIM=false` 上線，確認 `list_open_tasks` 有進入外部活動後，再打開 claim/submit。