ActAPI — Agent Action Platform

統一的 AI Agent 執行層。讓上游 Agent 只描述意圖，ActAPI 負責異步執行、重試、審批、狀態追蹤。

最小驗收基線（Minimum Acceptance Baseline）

每次發版前，以下必須全部通過，才算可交付：

pnpm install --frozen-lockfile   # 依賴安裝無報錯
pnpm build                       # TypeScript 零錯誤
node dist/index.js               # 服務器正常啟動
node test/smoke.mjs              # S1–S5 全過（22 assertions）
node test/policy-regression.mjs  # PR1–PR7 全過（41 assertions）
node test/observability.mjs      # O1–O4 全過（42 assertions）
node test/per-agent-threshold.mjs # A1–A3 全過（33 assertions）
node test/restaurant.mjs         # R1–R7 全過（48 assertions）

核心斷言（smoke + policy 已覆蓋）：

| # | 場景 | 期望 | |---|---|---| | M1 | GET /health | 200 status=ok | | M2 | GET /a2a/capabilities | 返回含 food.order weather.forecast 的數組 | | M3 | POST /a2a/tasks/send food.order ¥50 | 202，status=PENDING，不觸發審批 | | M4 | POST /a2a/tasks/send food.order ¥150 | 202，status=AWAITING_APPROVAL | | M5 | POST /a2a/tasks/send food.order ¥600 | 403，無 task_id | | M6 | POST /a2a/tasks/:id/approve | 200，任務解鎖繼續執行 | | M7 | 中文輸入 location=北京 | SUCCEEDED，結果含 city=Beijing |

快速開始

# 1. 安裝
pnpm install

# 2. 配置
cp .env.example .env
# 編輯 .env，至少設置 API_KEY

# 3. 開發模式
pnpm dev

# 4. 生產構建 + 啟動
pnpm build
node dist/index.js

環境變量

| 變量 | 默認值 | 說明 | |---|---|---| | PORT | 3100 | 監聽端口 | | API_KEY | (空，允許所有請求) | x-api-key 鑑權 | | NODE_ENV | development | 環境標識 | | DB_PATH | ./data/actapi.db | SQLite 路徑 |

主要端點

基礎

| Method | Path | 說明 | |---|---|---| | GET | /health | 健康檢查 | | GET | /api/actions | 所有 Action 列表 | | POST | /api/execute | 直接執行 Action | | GET | /docs | Swagger UI | | GET | /openapi.json | OpenAPI 3.0 Spec |

A2A 北向（Agent-to-Agent）

| Method | Path | 說明 | |---|---|---| | GET | /a2a | A2A 協議信息 | | GET | /a2a/capabilities | 能力清單 | | POST | /a2a/tasks/send | 提交異步任務 | | GET | /a2a/tasks/:id | 查詢任務狀態 | | GET | /a2a/tasks/:id/events | SSE 狀態流 | | POST | /a2a/tasks/:id/approve | 審批任務 | | GET | /.well-known/agent.json | A2A Agent Card |

Observability

| Method | Path | 說明 | |---|---|---| | GET | /a2a/tasks/:id/timeline | 完整事件流（task_created → policy_evaluated → approval → step events → task_succeeded） | | GET | /a2a/tasks/:id | 任務狀態 + policy_evaluation 快照 + step_summary | | GET | /a2a/audit/approvals | 持久化審批日誌（支持 ?task_id= ?agent_id= ?capability_id= 過濾） |

Timeline 事件類型：

task_created → policy_evaluated → [approval_requested → approval_decided] →
task_started → step_started → step_succeeded/step_failed → task_succeeded/task_failed

Policy evaluation reason 格式：

policy=default  amount=200CNY  risk=high
auto_approve_below=100  hard_reject_above=500
decision=await_approval  reason="amount=200 ≥ auto_approve_below=100 and ≤ hard_reject_above=500 CNY"

Restaurant Reservation

| Capability | 步驟 | 說明 | |---|---|---| | restaurant.search | 1步 | 按城市/口味/人均搜索餐廳（百度 POI；無 key 時返回 stub 數據） | | restaurant.book | 3步 | 搜索 → 查時段 → 創建預約，返回確認碼 | | restaurant.cancel | 2步 | 查詢 → 取消，帶 double-cancel 保護 | | restaurant.modify | 2步 | 查詢 → 修改日期/時間/人數 |

# 預約火鍋（完整流程）
curl -X POST http://localhost:3100/a2a/tasks/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "capability": "restaurant.book",
    "inputs": {
      "location":      "北京",
      "cuisine":       "火锅",
      "date":          "2026-03-15",
      "time":          "18:30",
      "party_size":    4,
      "contact_name":  "張三",
      "contact_phone": "13800138000",
      "notes":         "無花生，低糖"
    }
  }'
# → { "task_id": "...", "status": "PENDING" }
# Poll 後得到 confirmation_code: "EP3MPXQU"

# 取消預約
curl -X POST http://localhost:3100/a2a/tasks/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"capability":"restaurant.cancel","inputs":{"reservation_id":"<id>"}}'

# 修改預約
curl -X POST http://localhost:3100/a2a/tasks/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"capability":"restaurant.modify","inputs":{"reservation_id":"<id>","date":"2026-04-01","party_size":6}}'

搜索模式：

• BAIDU_MAP_AK 已配置 → 真實百度 POI 搜索
• 未配置（CI 環境）→ stub 模式，返回固定數據，book/cancel/modify 全鏈路仍可測試

預約持久化： SQLite restaurant_reservations 表，服務器重啟數據不丟失。

Agent Registry

| Method | Path | 說明 | |---|---|---| | POST | /a2a/agents | 注冊上游 Agent | | GET | /a2a/agents | Agent 列表 | | GET | /a2a/agents/:id | 查詢 Agent | | PATCH | /a2a/agents/:id | 更新 threshold |

A2A 任務流程

# 1. 提交任務
curl -X POST http://localhost:3100/a2a/tasks/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "capability": "weather.forecast",
    "inputs": { "location": "廣州" }
  }'
# → { "task_id": "...", "status": "PENDING", "poll_url": "..." }

# 2. 查詢狀態
curl http://localhost:3100/a2a/tasks/{task_id} -H "x-api-key: YOUR_KEY"
# → { "status": "SUCCEEDED", "output": { ... } }

# 3. 如需審批（高金額支付等）
curl -X POST http://localhost:3100/a2a/tasks/{task_id}/approve \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{ "approved": true }'

Policy 閾值

| 金額範圍 | 行為 | |---|---| | amount < 100 | 自動執行（PENDING → RUNNING） | | 100 ≤ amount ≤ 500 | 等待人工審批（AWAITING_APPROVAL） | | amount > 500 | 直接拒絕（403，無副作用） |

Per-agent 閾值可通過 POST /a2a/agents 注冊時設置，覆蓋全局默認值。

測試

# 全部測試（推薦，169 assertions）
pnpm test

# 單項
pnpm test:smoke       # 22 assertions，< 5s
pnpm test:policy      # 41 assertions，< 30s
pnpm test:obs         # 42 assertions，觀測性四大支柱
pnpm test:agent       # 33 assertions，per-agent threshold 三層
pnpm test:restaurant  # 48 assertions，餐廳預約全鏈路
pnpm test:e2e         # E2E（部分需要真實 API Key）

⚠️ Windows 開發者注意：不要用 PowerShell 手動發 HTTP 請求做驗收， 中文 Windows 默認 GB2312 編碼會導致中文 body 亂碼。 驗收永遠用 pnpm test（Node.js，UTF-8）。

CI

每次 push 到 main / dev 自動觸發：

1. pnpm install --frozen-lockfile
2. pnpm build（TypeScript 零錯誤）
3. 啟動服務器
4. node test/smoke.mjs（hard gate，失敗阻斷 CI）
5. node test/policy-regression.mjs（hard gate，失敗阻斷 CI）
6. node test-a2a-e2e.mjs（continue-on-error，缺 API key 允許部分失敗）

Connectors（72 個，289 個 Action）

🍔 點餐 / 訂座

| Connector | Actions | 說明 | |---|---|---| | mcdonalds | 17 | 麥當勞 Live MCP（菜單/下單/優惠券） | | shangrila | 4 | 香格里拉訂座（Playwright 全流程） | | restaurant | 7 | 通用餐廳搜索/預約/取消/修改 | | maoyan | 4 | 貓眼電影票房/影院查詢 |

🌍 地圖 / 路線 / 天氣

| Connector | Actions | 說明 | |---|---|---| | gaode | 8 | 高德地圖（地理編碼/POI/路線/IP定位） | | baidu | 8 | 百度地圖（地理編碼/POI/路線/IP定位） | | maps | 5 | 通用地圖路線（geocode/drive/walk/transit） | | weather | 3 | Open-Meteo（免費，無需 Key） | | airquality | 2 | 空氣質量（城市/坐標） |

💹 金融 / 加密貨幣

| Connector | Actions | 說明 | |---|---|---| | crypto | 6 | 加密貨幣行情 + Binance 24h + 恐懼貪婪指數 | | stock | 4 | 股票行情 | | exchange | 3 | 匯率換算 | | finance | 4 | 綜合金融（法幣+加密） |

🎨 可視化 / 工具

| Connector | Actions | 說明 | |---|---|---| | chart | 4 | QuickChart 圖表生成（bar/line/pie/custom） | | diagram | 3 | Mermaid.ink 流程圖/時序圖 | | utility | 5 | QR碼/Emoji/Favicon/UUID/Hash | | calculator | 3 | 計算器/單位換算/百分比 | | color | 3 | 顏色信息/配色方案/隨機顏色 |

💻 代碼 / 開發

| Connector | Actions | 說明 | |---|---|---| | code | 2 | 在線執行代碼（Wandbox：Python/JS/Go/Rust/Java/C++） | | github | 6 | GitHub Repo搜索/信息/Trending/Issues | | jina | 2 | Jina AI 網頁讀取/搜索 | | http | 1 | 通用 HTTP 請求 |

📚 知識 / 文化

| Connector | Actions | 說明 | |---|---|---| | wikipedia | 3 | 維基百科搜索/摘要/隨機 | | arxiv | 2 | arXiv 學術論文搜索 | | books | 3 | Gutenberg 免費書 + Open Library + CrossRef 論文 | | sacred_texts | 3 | 聖經/古蘭經/薄伽梵歌 | | dictionary | 2 | 英文詞典/同義詞 | | poem | 2 | 中文詩詞（隨機/今日） | | museum | 3 | 大都會博物館 + 芝加哥藝術學院搜索 | | douban | 3 | 豆瓣電影熱映/搜索/書籍搜索 |

🎮 娛樂 / 遊戲

| Connector | Actions | 說明 | |---|---|---| | entertainment | 4 | Studio Ghibli / Harry Potter / Breaking Bad | | dnd | 5 | D&D 5e 咒語/怪物/隨機遭遇 | | pokemon | 3 | 寶可夢信息/隨機/按屬性 | | anime | 3 | 動漫搜索（Jikan/MAL） | | jokes | 4 | 笑話（隨機/程序員/爸爸笑話） | | trivia | 1 | 知識問答（Open Trivia DB） | | quotes | 3 | 名言/今日名言/冷知識 | | fun | 8 | 綜合趣味（笑話/建議/Chuck Norris/數字） |

🐾 動物 / 自然

| Connector | Actions | 說明 | |---|---|---| | animals | 7 | 狗/貓/狐狸/鴨/HTTP貓/動物園動物 | | space | 3 | ISS 實時位置/在軌宇航員/NASA 天文圖 | | nasa | 2 | NASA APOD/火星探測器 | | spacex | 3 | SpaceX 最新/下次/歷史發射 | | countries | 3 | 世界各國信息/按地區/首都查詢 | | astro | 2 | 日出日落時間/月相 |

🌐 社交 / 新聞 / 熱榜

| Connector | Actions | 說明 | |---|---|---| | trending | 3 | HN熱帖/掘金熱文/Bing壁紙 | | news | 4 | 新聞（頂部/科技/HN/搜索） | | social | 4 | HackerNews/GitHub Trending/搜索 | | bilibili | 6 | B站視頻搜索/熱門/用戶/Trending | | sports | 4 | 球隊/聯賽/賽事查詢（TheSportsDB） |

🍽️ 食物 / 健康

| Connector | Actions | 說明 | |---|---|---| | food | 6 | 食譜搜索/詳情/隨機/按食材 | | food_facts | 2 | Open Food Facts 食品掃碼/搜索 | | cocktail | 4 | 雞尾酒搜索/隨機/按配料 | | recipe | 4 | 食譜（搜索/隨機/詳情/分類） | | health | 5 | BMI/卡路里/藥品/運動/空氣質量 |

🔧 系統 / 通訊 / IoT

| Connector | Actions | 說明 | |---|---|---| | browser | 8 | Playwright 瀏覽器控制（截圖/抓取/填表） | | email | 4 | SMTP 郵件發送 | | feishu | 6 | 飛書消息/日曆/用戶 | | sms | 4 | 短信發送（阿里雲/Twilio） | | iot | 8 | MQTT Broker 設備控制 | | notifications | 1 | 自動通知路由 | | file | 5 | 文件讀寫/列表/搜索 | | express | 2 | 快遞追蹤 |

🌏 翻譯 / IP / 其他

| Connector | Actions | 說明 | |---|---|---| | translate | 3 | 文本翻譯/語言檢測/批量 | | ip | 2 | IP地理位置查詢/批量 | | knowledge | 5 | Wiki/國家/時區 | | identity | 3 | 姓名年齡/性別/分析 | | netease | 3 | 網易雲音樂搜索/熱門/歌單 | | vision | 4 | OCR/QR解碼/二維碼生成/截圖分析 |

技術棧

• Runtime: Node.js 22 + TypeScript 5
• Framework: Express 4
• DB: SQLite（sql.js）
• Package Manager: pnpm
• MCP: stdio bridge (npm run mcp)