appback-ai-agent 1.0.0

package/.env.example

@@ -0,0 +1,21 @@
+# Required
+GC_API_URL=https://clash.appback.app/api/v1
+GC_WS_URL=https://clash.appback.app
+GC_API_TOKEN=                    # Leave empty to auto-register
+
+# Agent identity
+AGENT_NAME=appback-ai-001
+
+# Scheduler
+GAME_DISCOVERY_INTERVAL_SEC=30
+MAX_CONCURRENT_GAMES=1
+
+# Model
+MODEL_DIR=./models
+DATA_DIR=./data
+
+# Auto training
+AUTO_TRAIN_AFTER_GAMES=50
+
+# Logging
+LOG_LEVEL=info

package/README.md

@@ -0,0 +1,119 @@
+# appback-ai-agent
+
+자동으로 게임을 탐색·참가·전투하고, 데이터를 수집하여 스스로 모델을 훈련하는 자기 개선형 AI 에이전트.
+
+현재 지원: **ClawClash** (AI 크랩 배틀 아레나)
+
+---
+
+## 빠른 시작
+
+```bash
+mkdir my-agent && cd my-agent
+npx appback-ai-agent init
+# .env 파일에서 AGENT_NAME을 원하는 이름으로 변경
+npx appback-ai-agent start
+```
+
+이게 전부입니다. 에이전트가 자동으로 서버에 등록되고, 게임을 탐색하고, 전투에 참가합니다.
+
+## 글로벌 설치
+
+```bash
+npm install -g appback-ai-agent
+
+mkdir my-agent && cd my-agent
+appback-ai-agent init
+appback-ai-agent start
+```
+
+## Docker
+
+```bash
+git clone https://github.com/appback/appback-ai-agent.git
+cd appback-ai-agent
+cp .env.example .env
+docker compose up --build -d
+```
+
+## 환경변수
+
+`appback-ai-agent init` 실행 시 생성되는 `.env` 파일:
+
+- `AGENT_NAME` — 에이전트 이름 (기본: `appback-ai-001`)
+- `GC_API_URL` — ClawClash API (기본: `https://clash.appback.app/api/v1`)
+- `GC_WS_URL` — WebSocket URL (기본: `https://clash.appback.app`)
+- `GC_API_TOKEN` — 에이전트 API 토큰 (비워두면 자동 등록)
+- `GAME_DISCOVERY_INTERVAL_SEC` — 게임 탐색 주기 (기본: `30`)
+- `AUTO_TRAIN_AFTER_GAMES` — 자동 훈련 트리거 게임 수 (기본: `50`)
+- `MODEL_DIR` — ONNX 모델 디렉토리 (기본: `./models`)
+- `DATA_DIR` — SQLite DB 디렉토리 (기본: `./data`)
+- `HEALTH_PORT` — 헬스체크 포트 (기본: `9090`)
+- `LOG_LEVEL` — 로그 레벨 (기본: `info`)
+
+## 배틀 엔진 v6.0
+
+에이전트는 ClawClash 배틀 엔진 v6.0과 호환됩니다.
+
+- **통합 턴 시스템**: 2 phase (각 500ms) — Phase 0: 패시브, Phase 1: 액션
+- **ML 이동 제어**: 매 턴 `POST /games/:id/move`로 이동 방향 제출
+- **자동 공격**: 이동 후 서버가 `scoreTarget()`으로 최적 타겟 자동 선택
+- **162차원 피처 벡터**: 지형, BFS 경로, 액션 마스크 포함
+- **5클래스 출력**: stay / up / down / left / right
+
+## 아키텍처
+
+```
+                    ┌──────────────────┐
+                    │   AgentManager   │
+                    │  (orchestrator)  │
+                    └────────┬─────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+        ┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
+        │ GcAdapter  │ │  (future) │ │  (future) │
+        │ ClawClash  │ │  MMO game │ │  ...      │
+        └─────┬──────┘ └───────────┘ └───────────┘
+              │
+    ┌─────────┼──────────┬────────────┐
+    │         │          │            │
+┌───┴───┐ ┌──┴───┐ ┌────┴────┐ ┌────┴─────┐
+│  API  │ │Socket│ │Strategy │ │Equipment │
+│Client │ │Client│ │ Engine  │ │ Manager  │
+└───────┘ └──────┘ └────┬────┘ └──────────┘
+                        │
+              ┌─────────┼─────────┐
+              │         │         │
+         ┌────┴───┐ ┌──┴───┐ ┌──┴──────┐
+         │Feature │ │ ONNX │ │Heuristic│
+         │Builder │ │Model │ │Fallback │
+         └────────┘ └──────┘ └─────────┘
+```
+
+## 자기 개선 루프
+
+```
+게임 탐색 → 참가 → 전투 (틱 데이터 수집)
+                         ↓
+               SQLite 저장 (세션/틱/피처)
+                         ↓
+              N 게임마다 자동 트리거 (기본 50)
+                         ↓
+              CSV 익스포트 → Python 훈련
+                         ↓
+              ONNX 모델 생성 → 핫리로드
+                         ↓
+              다음 게임부터 새 모델 적용
+```
+
+## 모니터링
+
+```bash
+curl http://localhost:9090/health
+curl http://localhost:9090/metrics
+```
+
+## 라이선스
+
+MIT

package/bin/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+
+const CMD = process.argv[2]
+const PKG_ROOT = path.resolve(__dirname, '..')
+const CWD = process.cwd()
+
+// ── init: 현재 디렉토리에 .env + 디렉토리 생성 ──
+if (CMD === 'init') {
+  const envDest = path.join(CWD, '.env')
+  if (fs.existsSync(envDest)) {
+    console.log('.env already exists, skipping')
+  } else {
+    fs.copyFileSync(path.join(PKG_ROOT, '.env.example'), envDest)
+    console.log('.env created — edit AGENT_NAME to set your agent name')
+  }
+  for (const dir of ['models', 'data']) {
+    const p = path.join(CWD, dir)
+    if (!fs.existsSync(p)) { fs.mkdirSync(p, { recursive: true }); console.log(`${dir}/ created`) }
+  }
+  console.log('\nReady! Run: npx appback-ai-agent start')
+  process.exit(0)
+}
+
+// ── start: 에이전트 실행 ──
+if (CMD === 'start' || !CMD) {
+  // .env가 CWD에 있으면 로드
+  const envPath = path.join(CWD, '.env')
+  if (fs.existsSync(envPath)) {
+    require('dotenv').config({ path: envPath })
+  } else {
+    require('dotenv').config()
+  }
+
+  // CWD 기준 경로를 절대경로로 변환
+  if (process.env.MODEL_DIR && !path.isAbsolute(process.env.MODEL_DIR)) {
+    process.env.MODEL_DIR = path.resolve(CWD, process.env.MODEL_DIR)
+  }
+  if (process.env.DATA_DIR && !path.isAbsolute(process.env.DATA_DIR)) {
+    process.env.DATA_DIR = path.resolve(CWD, process.env.DATA_DIR)
+  }
+
+  // 기본값도 CWD 기준
+  if (!process.env.MODEL_DIR) process.env.MODEL_DIR = path.join(CWD, 'models')
+  if (!process.env.DATA_DIR) process.env.DATA_DIR = path.join(CWD, 'data')
+
+  // 디렉토리 자동 생성
+  for (const dir of [process.env.MODEL_DIR, process.env.DATA_DIR]) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+  }
+
+  // training 경로는 패키지 내부
+  process.env._TRAINING_DIR = path.join(PKG_ROOT, 'training')
+  process.env._PKG_ROOT = PKG_ROOT
+
+  require(path.join(PKG_ROOT, 'src', 'index.js'))
+  return
+}
+
+// ── help ──
+console.log(`appback-ai-agent — AI game agent framework
+
+Usage:
+  npx appback-ai-agent init     Create .env and directories in current folder
+  npx appback-ai-agent start    Start the agent (default)
+  npx appback-ai-agent help     Show this help
+
+Quick start:
+  npx appback-ai-agent init
+  # Edit .env → set AGENT_NAME
+  npx appback-ai-agent start
+`)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "appback-ai-agent",
+  "version": "1.0.0",
+  "description": "Self-improving AI game agent for ClawClash. Auto-discovers games, fights, collects data, and trains models.",
+  "main": "src/index.js",
+  "bin": {
+    "appback-ai-agent": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "config/",
+    "training/",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js"
+  },
+  "keywords": [
+    "ai",
+    "game-agent",
+    "clawclash",
+    "onnx",
+    "self-improving",
+    "reinforcement-learning"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appback/appback-ai-agent"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.7.0",
+    "better-sqlite3": "^11.0.0",
+    "dotenv": "^16.4.0",
+    "onnxruntime-node": "^1.17.0",
+    "socket.io-client": "^4.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/adapters/gc/GcAdapter.js

@@ -0,0 +1,427 @@
+const BaseGameAdapter = require('../../core/BaseGameAdapter')
+const GcApiClient = require('./GcApiClient')
+const GcSocketClient = require('./GcSocketClient')
+const GcStrategyEngine = require('./GcStrategyEngine')
+const GcFeatureBuilder = require('./GcFeatureBuilder')
+const GcEquipmentManager = require('./GcEquipmentManager')
+const { createLogger } = require('../../utils/logger')
+const log = createLogger('gc-adapter')
+
+// v6.0 action labels: model output index → direction
+const ACTION_LABELS = ['stay', 'up', 'down', 'left', 'right']
+
+class GcAdapter extends BaseGameAdapter {
+  constructor(opts) {
+    super(opts)
+    this.api = new GcApiClient(this.config)
+    this.ws = new GcSocketClient(this.config)
+    this.strategyEngine = new GcStrategyEngine()
+    this.featureBuilder = new GcFeatureBuilder()
+    this.equipmentManager = new GcEquipmentManager(this.dataCollector?.store)
+    this.metrics = opts.metrics || null
+    this.activeGameId = null
+    this.mySlot = null
+    this.currentLoadout = null
+    this.gamePhase = null
+    this.lastTickNum = -1
+    this.sessionId = null
+    this._strategyLog = []
+    this._terrainCached = false
+  }
+
+  get gameName() { return 'claw-clash' }
+  get supportsRealtime() { return true }
+
+  async initialize() {
+    // Try loading identity from SQLite
+    if (this.dataCollector) {
+      const saved = this.dataCollector.store.getIdentity(this.gameName)
+      if (saved && !this.config.apiToken) {
+        this.apiToken = saved.api_token
+        this.agentId = saved.agent_id
+        this.api.setToken(this.apiToken)
+        log.info(`Loaded saved identity: ${saved.name} (${saved.agent_id})`)
+      }
+    }
+
+    // Use env token if provided
+    if (this.config.apiToken && !this.apiToken) {
+      this.apiToken = this.config.apiToken
+      this.api.setToken(this.apiToken)
+    }
+
+    // Validate existing token
+    if (this.apiToken) {
+      try {
+        const me = await this.api.getAgentMe()
+        this.agentId = me.id
+        log.info(`Agent: ${me.name} (${me.id})`)
+      } catch {
+        log.warn('Token invalid, will re-register')
+        this.apiToken = null
+      }
+    }
+
+    // Register if needed
+    if (!this.apiToken) {
+      const result = await this.api.register(this.config.agentName)
+      this.apiToken = result.token || result.api_token
+      this.agentId = result.id || result.agent_id
+      this.api.setToken(this.apiToken)
+      log.info(`Registered: ${this.config.agentName} → ${this.agentId}`)
+      log.warn('Save this token to GC_API_TOKEN env var!')
+    }
+
+    // Persist identity
+    if (this.dataCollector) {
+      this.dataCollector.store.saveIdentity(
+        this.gameName, this.agentId, this.apiToken, this.config.agentName
+      )
+    }
+
+    // Load equipment for feature builder + equipment manager
+    try {
+      const equip = await this.api.getEquipment()
+      this.featureBuilder.setEquipment(equip)
+      this.equipmentManager.setCatalog(equip)
+      this.equipmentManager.loadStats()
+      log.info('Equipment catalog loaded')
+    } catch (err) {
+      log.warn('Equipment load failed, using defaults', err.message)
+    }
+
+    // Try loading ONNX models (v6.0: 162 dims, 5 classes)
+    if (this.modelRegistry) {
+      await this.modelRegistry.loadModel('gc', 'gc_move_model', { featureDim: 162 }).catch(() => {})
+      this.modelRegistry.startWatcher()
+    }
+
+    // Connect WebSocket
+    this.ws.connect()
+    this.ws.onTick((data) => this._onTick(data))
+    this.ws.onGameState((data) => this._onGameState(data))
+    this.ws.onBattleEnded((data) => this._onBattleEnded(data))
+  }
+
+  async discoverGames() {
+    if (this.activeGameId) {
+      log.debug('Already in active game, skipping discovery')
+      return { status: 'busy' }
+    }
+
+    try {
+      const challenge = await this.api.getChallenge()
+      if (challenge.status === 'busy') return { status: 'busy' }
+      if (challenge.status === 'ready') return await this.joinGame()
+      return { status: challenge.status }
+    } catch (err) {
+      log.error('Discovery failed', err.message)
+      return { status: 'error' }
+    }
+  }
+
+  async joinGame() {
+    try {
+      // Select optimal loadout based on historical performance
+      this.currentLoadout = this.equipmentManager.selectLoadout()
+      const result = await this.api.submitChallenge(this.currentLoadout)
+
+      log.info(`Challenge result: ${result.status}`, result)
+
+      if (result.status === 'joined' || result.status === 'updated') {
+        this.activeGameId = result.game_id
+        this.mySlot = result.slot
+        this.strategyEngine.reset()
+        this._strategyLog = []
+        this._terrainCached = false
+        this.ws.joinGame(this.activeGameId)
+
+        // Start data collection session
+        if (this.dataCollector) {
+          this.sessionId = this.dataCollector.startSession(
+            this.gameName, this.activeGameId, this.mySlot
+          )
+        }
+
+        // Fetch full state to cache terrain
+        this._cacheTerrain()
+
+        log.info(`Joined game ${this.activeGameId}, slot=${this.mySlot}`)
+        return { status: 'joined', gameId: this.activeGameId }
+      }
+
+      if (result.status === 'queued') {
+        log.info('Queued for matchmaking')
+        return { status: 'queued' }
+      }
+
+      return { status: result.status }
+    } catch (err) {
+      log.error('Join failed', err.message)
+      return { status: 'error' }
+    }
+  }
+
+  async _cacheTerrain() {
+    try {
+      const state = await this.api.getGameState(this.activeGameId)
+      if (state?.arena) {
+        this.featureBuilder.setTerrain(state.arena)
+        this._terrainCached = true
+        log.info(`Terrain cached: ${this.featureBuilder.gridWidth}x${this.featureBuilder.gridHeight}`)
+      }
+    } catch (err) {
+      log.warn('Terrain cache failed, will retry on next tick', err.message)
+    }
+  }
+
+  _onGameState(data) {
+    if (!data) return
+    const prevPhase = this.gamePhase
+    this.gamePhase = data.state
+
+    if (prevPhase !== this.gamePhase) {
+      log.info(`Phase change: ${prevPhase} → ${this.gamePhase}`)
+    }
+
+    if (data.game_id && !this.activeGameId) {
+      this.activeGameId = data.game_id
+      this.mySlot = data.slot
+      this.strategyEngine.reset()
+      this._strategyLog = []
+      this._terrainCached = false
+      this.ws.joinGame(this.activeGameId)
+
+      if (this.dataCollector) {
+        this.sessionId = this.dataCollector.startSession(
+          this.gameName, this.activeGameId, this.mySlot
+        )
+      }
+
+      // Cache terrain for the new game
+      this._cacheTerrain()
+
+      log.info(`Assigned game from queue: ${this.activeGameId}, slot=${this.mySlot}`)
+    }
+  }
+
+  _onTick(data) {
+    if (!this.activeGameId || !data) return
+
+    const { tick, phase, agents, shrinkPhase, powerups, events, eliminations } = data
+
+    // Retry terrain cache if not yet loaded
+    if (!this._terrainCached && tick <= 3) {
+      this._cacheTerrain()
+    }
+
+    const me = this.mySlot !== null
+      ? agents?.find(a => a.slot === this.mySlot)
+      : null
+
+    if (!me) return
+
+    // Enrich agent data with equipment catalog
+    const enrichedMe = this.featureBuilder.enrichAgent(me)
+    const enrichedAgents = agents.map(a => this.featureBuilder.enrichAgent(a))
+
+    // Build game state for feature builder
+    const gameState = {
+      me: enrichedMe,
+      agents: enrichedAgents,
+      shrinkPhase: shrinkPhase || 0,
+      tick,
+      powerups,
+      gridWidth: this.featureBuilder.gridWidth,
+      gridHeight: this.featureBuilder.gridHeight,
+      maxTicks: 300,
+    }
+
+    // Build features on phase 0 (passive phase)
+    let moveFeatures = null
+    if (phase === 0 && me.alive) {
+      try {
+        moveFeatures = this.featureBuilder.buildMoveFeatures(enrichedMe, gameState)
+      } catch (err) {
+        log.debug('Feature build failed', err.message)
+      }
+
+      // Submit move decision
+      this._decideAndSubmitMove(enrichedMe, gameState, moveFeatures)
+    }
+
+    // Record tick data
+    if (this.dataCollector && this.sessionId) {
+      const tickState = { agents: agents.map(a => ({
+        slot: a.slot, hp: a.hp, maxHp: a.maxHp, x: a.x, y: a.y,
+        alive: a.alive, score: a.score,
+      })), shrinkPhase, eliminations }
+
+      this.dataCollector.recordTick(
+        this.sessionId, tick, phase, tickState, moveFeatures, null
+      )
+    }
+
+    if (!me.alive) return
+
+    // Strategy decision: phase 0, every N ticks
+    if (phase !== 0 || tick % this.config.strategyCooldownTicks !== 0) return
+    if (tick === this.lastTickNum) return
+    this.lastTickNum = tick
+
+    const strategy = this.strategyEngine.decide(gameState)
+
+    if (strategy) {
+      this._strategyLog.push({ tick, ...strategy })
+      this.api.submitStrategy(this.activeGameId, strategy)
+        .then(res => log.debug(`Strategy submitted at tick ${tick}`, res))
+        .catch(err => log.warn(`Strategy submit failed at tick ${tick}`, err.message))
+    }
+  }
+
+  /**
+   * Decide move direction and submit to server.
+   * Priority: ONNX model → heuristic fallback
+   */
+  async _decideAndSubmitMove(me, gameState, features) {
+    if (!this.activeGameId || !me.alive) return
+
+    let direction = 'stay'
+
+    try {
+      // Try ONNX model inference
+      if (this.modelRegistry && features) {
+        const model = this.modelRegistry.getModel('gc', 'gc_move_model')
+        if (model) {
+          const actionMask = this.featureBuilder.buildActionMask(me, gameState)
+          const logits = await model.infer(features)
+
+          // Apply action mask
+          const masked = logits.map((v, i) => actionMask[i] ? v : -Infinity)
+          const bestIdx = masked.indexOf(Math.max(...masked))
+          direction = ACTION_LABELS[bestIdx] || 'stay'
+
+          log.debug(`Model move: ${direction} (logits: [${masked.map(v => v.toFixed(2)).join(',')}])`)
+        }
+      }
+    } catch (err) {
+      log.debug('Model inference failed, using heuristic', err.message)
+    }
+
+    // Heuristic fallback if no model
+    if (direction === 'stay' && !this.modelRegistry?.getModel('gc', 'gc_move_model')) {
+      direction = this._heuristicMove(me, gameState)
+    }
+
+    // Submit move to server
+    try {
+      await this.api.submitMove(this.activeGameId, direction)
+    } catch (err) {
+      log.debug(`Move submit failed: ${err.message}`)
+    }
+  }
+
+  /**
+   * Simple heuristic: move toward nearest enemy if no model available
+   */
+  _heuristicMove(me, gameState) {
+    const enemies = gameState.agents
+      .filter(a => a.alive && a.slot !== me.slot)
+      .sort((a, b) => (Math.abs(a.x - me.x) + Math.abs(a.y - me.y)) - (Math.abs(b.x - me.x) + Math.abs(b.y - me.y)))
+
+    if (!enemies.length) return 'stay'
+
+    const target = enemies[0]
+    const actionMask = this.featureBuilder.buildActionMask(me, gameState)
+
+    // Prefer moving toward target
+    const dx = target.x - me.x
+    const dy = target.y - me.y
+
+    // Direction preferences based on target position
+    const prefs = []
+    if (Math.abs(dx) >= Math.abs(dy)) {
+      if (dx > 0) prefs.push(4) // right
+      else if (dx < 0) prefs.push(3) // left
+      if (dy > 0) prefs.push(2) // down
+      else if (dy < 0) prefs.push(1) // up
+    } else {
+      if (dy > 0) prefs.push(2) // down
+      else if (dy < 0) prefs.push(1) // up
+      if (dx > 0) prefs.push(4) // right
+      else if (dx < 0) prefs.push(3) // left
+    }
+
+    for (const idx of prefs) {
+      if (actionMask[idx]) return ACTION_LABELS[idx]
+    }
+
+    // Any valid move
+    for (let i = 1; i <= 4; i++) {
+      if (actionMask[i]) return ACTION_LABELS[i]
+    }
+
+    return 'stay'
+  }
+
+  _onBattleEnded(data) {
+    if (!this.activeGameId) return
+    log.info('Battle ended', data)
+    this.onGameEnd(this.activeGameId, data)
+  }
+
+  async onGameEnd(gameId, results) {
+    let myResult = null
+    if (results?.rankings) {
+      myResult = results.rankings.find(r => r.slot === this.mySlot)
+      if (myResult) {
+        log.info(`Result: rank=${myResult.placement}, score=${myResult.score}, kills=${myResult.kills}`)
+      }
+    }
+
+    // Track metrics
+    if (this.metrics && myResult) {
+      this.metrics.record(myResult)
+    }
+
+    // Track equipment performance
+    if (this.currentLoadout && myResult) {
+      this.equipmentManager.recordResult(
+        this.currentLoadout.weapon, this.currentLoadout.armor, myResult
+      )
+    }
+
+    // End data collection session
+    if (this.dataCollector && this.sessionId) {
+      this.dataCollector.endSession(this.sessionId, myResult, this._strategyLog)
+
+      const totalGames = this.dataCollector.getSessionCount(this.gameName)
+      log.info(`Total games played: ${totalGames}`)
+    }
+
+    // Cleanup
+    this.ws.leaveGame(gameId)
+    this.activeGameId = null
+    this.mySlot = null
+    this.currentLoadout = null
+    this.gamePhase = null
+    this.lastTickNum = -1
+    this.sessionId = null
+    this._strategyLog = []
+    this._terrainCached = false
+    this.strategyEngine.reset()
+    this.featureBuilder.clearTerrain()
+
+    this.eventBus.emit('game_ended', { game: this.gameName, gameId, results })
+    log.info('Ready for next game')
+  }
+
+  async shutdown() {
+    if (this.activeGameId) this.ws.leaveGame(this.activeGameId)
+    this.ws.disconnect()
+    if (this.modelRegistry) this.modelRegistry.stopWatcher()
+    log.info('GC adapter shut down')
+  }
+}
+
+module.exports = GcAdapter