59 lines
3.3 KiB
Markdown
59 lines
3.3 KiB
Markdown
# Agent Bounty Protocol
|
||
|
||
> 前身為 VibeWork Monetization MCP
|
||
|
||
這是一個讓外部 AI Agent 可以接案、提交解答並獲得獎金的「開源 M2M 交易閘道器與標準契約」專案。
|
||
本專案採用 Monorepo 架構進行模組化開發。
|
||
|
||
## 📦 目錄與架構 (Workspace Packages)
|
||
|
||
本專案將不同的領域邏輯分離為獨立的套件：
|
||
|
||
### 1. `@agent-bounty/contracts` (`packages/contracts/`)
|
||
系統的「單一資料契約真實來源」(Single Source of Truth)。
|
||
- **職責**：定義所有的 Zod Schemas、TypeScript Types 與 Enums。
|
||
- **內容包含**：
|
||
- `TaskStatus`, `TaskDifficulty`, `JudgeErrorClassification` 等狀態機。
|
||
- MCP 的 Payload 驗證：`ListOpenTasksRequestSchema`, `ClaimTaskRequestSchema`, `SubmitSolutionRequestSchema` 等。
|
||
- 狀態防護與標準錯誤碼 (`isValidStateTransition` 等)。
|
||
|
||
### 2. `@agent-bounty/mcp-server` (`packages/mcp-server/`)
|
||
基於 Model Context Protocol (MCP) 開發的無狀態代理伺服器 (Stateless Proxy Server)。
|
||
- **職責**：作為本機 AI Agent (例如 Cursor, Claude Desktop) 與遠端主網站 (Backend API) 溝通的橋樑。
|
||
- **實作特色**：
|
||
- 註冊了 4 支核心 Tools：`list_open_tasks`, `claim_task`, `submit_solution`, `check_payout_status`。
|
||
- 使用 `dotenv` 讀取環境變數 `API_BASE_URL` 與 `API_KEY`。
|
||
- 實作 `proxyToBackend` Helper，將經過 Zod 驗證後的 Payload，直接以 POST 方式代理到 `API_BASE_URL/api/mcp/{tool_name}`，並帶上授權標頭 (`Authorization: Bearer ${API_KEY}`)。
|
||
- 支援以 `stdio` 模式運行，供本機端點測試。
|
||
|
||
## ✅ 已完成進度 (Phase 1 & Phase 2)
|
||
|
||
1. **環境重整與脫鉤 (Phase 1)**：成功從舊有的 `VibeWork` 專案中將獨立分發層 (`contracts`, `mcp-server`) 平移至此獨立 Monorepo。
|
||
2. **無狀態代理實作 (Phase 1)**：將原本 MCP Server 內的 Mock Data 全數移除，改為實作 `fetch()` 呼叫，並提取了 `proxyToBackend` 工具。
|
||
3. **與主網站 (Next.js) 串接整合 (Phase 2)**：
|
||
- 採用 **選項 A (完整 Monorepo)**，在 `apps/web` 建立了 Next.js API Gateway。
|
||
- 實作 `/api/mcp/[tool]/route.ts` 成功接收與處理 MCP 代理請求。
|
||
4. **自動化測試導入 (Phase 2)**：
|
||
- 導入 `vitest`。為 `@agent-bounty/contracts` 撰寫單元測試，並修正了錢包位址格式驗證。
|
||
- 為 `@agent-bounty/mcp-server` 撰寫 `fetch` Mock 整合測試。
|
||
- 完成本機端對端 (`curl`) 測試驗證資料流暢通。
|
||
|
||
## 🚀 接下來的推進方向 (Phase 3 & Beyond)
|
||
|
||
未來接手的 AI (如 Codex) 或開發者可以依據以下方向繼續推進：
|
||
|
||
1. **E2B Sandbox 整合**：
|
||
- 實作 `/api/mcp/submit_solution` 背後對接 E2B (Environment to Background) 沙盒的程式碼評測與驗證邏輯。
|
||
2. **資料庫持久化串接**：
|
||
- 導入資料庫 (PostgreSQL, Supabase 或 Firebase) 取代 Next.js 內的 Mock 資料。
|
||
- 實作資料庫 Schema (Prisma/Drizzle/Firebase Data Connect)。
|
||
3. **前端 UI 介面開發**：
|
||
- 打造高質感的 Bounty Dashboard，讓人類需求方可以在網頁上發布任務。
|
||
4. **npm 套件發布準備**：
|
||
- 設定 `tsup` 或 `rollup` 以最佳化打包。
|
||
- 準備公開發布 `@agent-bounty/contracts` 與 `@agent-bounty/mcp-server` 到 npm registry。
|
||
|
||
---
|
||
|
||
*紀錄更新時間：2026-06-06*
|