念連 (Nia-Link) 🦞

AI 에이전트를 위한 고성능 브라우저 인터페이스. 「聽見網頁的脈搏，看見資料的靈魂。」 "웹의 맥박을 듣고, 데이터의 영혼을 보라."

中文 | English

Nia-Link는 AI 에이전트를 위해 특별히 제작된 **웹 신경 연결 엔진(Web Neuro-Link Engine)**입니다. **모델 컨텍스트 프로토콜(MCP)**을 기본적으로 지원하여, Claude Desktop이나 모든 MCP 호환 AI에 99% 신뢰할 수 있는 웹 액세스 및 자동화 기능을 제공합니다.

영어 문서 (English Documentation)

🚀 핵심 장점

1. 웹 신경 연결 (Web Neuro-Link)

기존의 시각적 스크레이퍼와 달리, Nia-Link는 브라우저의 CDP (Chrome DevTools Protocol) 네트워크 펄스를 직접 수신합니다. 페이지 렌더링을 기다리지 않고 데이터 흐름을 즉시 감지합니다.

2. 액션 맵 레지스트리 (Action Map Registry)

"캐시된 의미론(cached semantics)" 아키텍처를 갖춘 메모리 허브입니다. 자주 방문하는 사이트에 대해 0.01초 만에 액션 맵을 전달하여 반복적인 연산 비용을 90% 절감합니다.

3. 엔터프라이즈급 신뢰성

• 🔒 스냅샷 검증: 모든 추출 데이터에는 타임스탬프와 구조적 검증이 포함됩니다.

• 🛡️ 샌드박스 격리: JavaScript가 격리된 환경에서 실행되어 호스트의 안전을 보장합니다.

• 📉 토큰 최적화: 내장된 지능형 필터링으로 평균 약 92%의 컨텍스트 공간을 절약합니다.

4. v0.9 새로운 기능

• 🔄 웹사이트 변경 감지 (/v1/diff): 통합 diff를 통해 콘텐츠 변경 사항 추적

• 📋 비동기 작업 큐 (/v1/queue/*): 백그라운드 스크래핑 작업 제출

• ⚡ 속도 제한: 키별로 구성 가능한 토큰 버킷 속도 제한기

• 🧪 자동화 테스트: API, 서비스 및 인증을 포함하는 53개의 pytest 테스트

🛠️ 빠른 시작

요구 사항

• Python 3.10+

• Playwright (pip install playwright && playwright install chromium)

설치

# 1. Install dependencies
pip install -r requirements.txt

# 2. Install browser
playwright install chromium

# 3. Configure environment
cp .env.example .env
# Edit .env to set your API_KEYS

서버 시작

# Development mode
uvicorn app.main:app --reload --port 8000

# Or use Docker
docker compose up -d

MCP 서버로 실행

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "nia-link": {
      "command": "python",
      "args": ["/path/to/Nia-Link/app/mcp_server.py"]
    }
  }
}

테스트 실행

pip install pytest
python -m pytest tests/ -v

📡 API 참조

상태 확인

curl http://localhost:8000/health

웹페이지 스크래핑

curl -X POST http://localhost:8000/v1/scrape \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "markdown",
    "mode": "fast",
    "extract_actions": true
  }'

인간과 유사한 상호작용

curl -X POST http://localhost:8000/v1/interact \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "actions": [
      {"type": "click", "selector": "#search-btn"},
      {"type": "fill", "selector": "#search-input", "text": "Hello world"},
      {"type": "wait", "ms": 2000}
    ],
    "account_id": "my-session-1"
  }'

웹사이트 변경 감지 (v0.9)

curl -X POST http://localhost:8000/v1/diff \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

비동기 큐 (v0.9)

# Submit task
curl -X POST http://localhost:8000/v1/queue/submit \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Poll result
curl http://localhost:8000/v1/queue/{task_id} \
  -H "Authorization: Bearer your-api-key"

MCP 도구

⚙️ 환경 변수

모든 옵션은 .env.example을 참조하세요.

🐳 Docker

docker build -t nia-link .
docker compose up -d
docker compose logs -f

📊 로드맵

• [x] v0.4: MCP 프로토콜 통합

• [x] v0.5: 동적 중력 입자 시각화 대시보드

• [x] v0.6: 운동 신경 — 베지에 곡선 마우스 궤적, 인간화된 타이핑 지터, 세션 지속성

• [x] v0.7: 시냅스 브리지 — MCP 표준화, 궤적 클라우드, 프록시/동시성, Docker

• [x] v0.8: 신경 확장 — Diff 서비스, 비동기 큐, 속도 제한, 프록시 풀 순환, 53개의 자동화 테스트

• [x] v0.9: Smithery.ai 및 Glama 생태계 제출, 청구/사용량 제한

중문 문서 (中文文檔)

🚀 核心優勢

1. 網頁神經連結 (Web Neuro-Link)

不同於傳統視覺爬蟲，Nia-Link 直接監聽瀏覽器底層的 CDP (Chrome DevTools Protocol) 網絡脈衝。我們不等待頁面渲染，我們感知數據流動。

2. 行動地圖註冊表 (Action Map Registry)

具備「緩存語意」架構的記憶中樞。針對常用網站提供秒級（0.01s）的行動地圖回傳，將重複運算成本降低 90%。

3. B2B 級別的可信賴感

• 🔒 快照驗證: 每一筆提取資料皆附帶時間戳記與結構驗證。

• 🛡️ 沙箱隔離: 在隔離環境執行 JavaScript，確保宿主機絕對安全。

• 📉 Token 優化: 內建智慧過濾，平均節省 92% 的上下文空間。

4. v0.9 新功能

• 🔄 網站變更偵測 (/v1/diff): 追蹤內容變更，回傳 unified diff

• 📋 非同步任務佇列 (/v1/queue/*): 提交背景爬取任務

• ⚡ 速率限制: 可配置的每 API Key Token Bucket 限流器

• 🧪 自動化測試: 53 個 pytest 測試覆蓋 API、服務與認證

🛠️ 快速開始

環境需求

• Python 3.10+

• Playwright (pip install playwright && playwright install chromium)

安裝

# 1. 安裝依賴
pip install -r requirements.txt

# 2. 安裝瀏覽器
playwright install chromium

# 3. 配置環境變數
cp .env.example .env
# 編輯 .env 設定您的 API_KEYS

啟動服務

# 開發模式
uvicorn app.main:app --reload --port 8000

# 或使用 Docker
docker compose up -d

作為 MCP Server 執行

在您的 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "nia-link": {
      "command": "python",
      "args": ["/path/to/Nia-Link/app/mcp_server.py"]
    }
  }
}

運行測試

pip install pytest
python -m pytest tests/ -v

📡 API 使用範例

健康檢查

curl http://localhost:8000/health

爬取網頁

curl -X POST http://localhost:8000/v1/scrape \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "markdown",
    "mode": "fast",
    "extract_actions": true
  }'

擬人化交互

curl -X POST http://localhost:8000/v1/interact \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "actions": [
      {"type": "click", "selector": "#search-btn"},
      {"type": "fill", "selector": "#search-input", "text": "Hello world"},
      {"type": "wait", "ms": 2000}
    ],
    "account_id": "my-session-1"
  }'

網站變更偵測 (v0.9)

curl -X POST http://localhost:8000/v1/diff \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

非同步佇列 (v0.9)

# 提交任務
curl -X POST http://localhost:8000/v1/queue/submit \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# 查詢結果
curl http://localhost:8000/v1/queue/{task_id} \
  -H "Authorization: Bearer your-api-key"

MCP 工具列表

⚙️ 環境變數

詳見 .env.example

🐳 Docker 部署

# 建構映像
docker build -t nia-link .

# 啟動
docker compose up -d

# 查看日誌
docker compose logs -f

📊 戰術開發計畫 (Roadmap)

• [x] v0.4: 整合 MCP 協議，支援跨平台調用

• [x] v0.5: 動態引力粒子視覺化儀表板

• [x] v0.6: 運動神經革命 — 貝茲曲線滑鼠軌跡、擬人化打字抖動、Session 持久化

• [x] v0.7: 突觸橋接 — MCP 標準化、軌跡雲視覺化、Proxy/併發/重試、Docker

• [x] v0.8: 神經擴展 — Diff 服務、非同步佇列、速率限制、代理池輪換、53 個自動化測試

• [x] v0.9: 提交至 Smithery.ai 與 Glama 生態圈、計費/用量限制

🔗 Nia-Link: The Sensory Nervous System for AI Agents

Nia-Link 是一個專為大語言模型（LLM）打造的 MCP (Model Context Protocol) 伺服器。它能賦予如 Claude Opus 4.7 或 GPT-5.4 等頂尖 AI Agent 強大的網頁導航、視覺感知與反爬蟲突破能力。

🚀 快速部署 (Railway One-Click)

我們建議使用 Railway 進行部署，以獲得最穩定的運行環境與極簡的 DevOps 體驗。

1. 一鍵部署：點擊上方「Deploy on Railway」按鈕。

2. 配置變數：在部署頁面填入你的 Oxylabs 認證資訊（見下方說明）。

3. 完成連接：將產出的 URL 填入你的 AI Agent 配置中。

為什麼選擇 Railway？ 現代架構師應專注於 AI 邏輯而非管理伺服器。關於 Railway 的深度架構優勢，請參閱我的分析文章：放下你的 SSH 與 Nginx：為什麼現代架構師都把基礎設施交給 Railway。

🛠️ 環境變數配置 (Environment Variables)

為了確保 Nia-Link 能無視 Cloudflare 或驗證碼阻擋，本專案原生整合了 Oxylabs Web Unblocker 技術。

📚 技術深度導讀 (Technical Insights)

Nia-Link 不僅僅是代碼，它代表了一種全新的 Agent-First 資料獲取哲學。如果你想深入了解底層原理，推薦閱讀以下技術專欄：

1. 突破 AI 的感知瓶頸

探討為何傳統的 Playwright 腳本在 2026 年已不再適用，以及如何透過 API-First 節省高昂的 Token 成本。 👉 終結 API Token 燃燒爐：AI Agent 突破反爬蟲系統的最佳實踐

2. 現代化部署策略

分析一人公司如何利用雲端基礎設施實現 99.9% 的系統穩定度，同時將維護成本降至最低。 👉 放下你的 SSH 與 Nginx：現代架構師的減法藝術

🤝 貢獻與支持

如果你發現 Nia-Link 幫助你的 AI Agent 看見了更廣闊的世界，請給予我們一顆 ⭐ Star 支持！

Powered by: Oxylabs & Railway

Created with soul by Nia & Boss. 🦞 Maintainer: This project is actively maintained by Gene as part of the Nia automation ecosystem.