mnemo_cards/ai_docs/agent/CONFIGURATION.md

# AI Agent System - Configuration Guide

Детальная инструкция по настройке системы AI агентов для Forgejo.

## Содержание

- [Требования](#требования)
- [Настройка Forgejo](#настройка-forgejo)
- [Настройка Secrets](#настройка-secrets)
- [Настройка Runners](#настройка-runners)
- [Cursor CLI](#cursor-cli)
- [Тестирование](#тестирование)
- [Troubleshooting](#troubleshooting)

## Требования

### Минимальные требования

- **Forgejo**: версия 1.20+ (с поддержкой Actions)
- **Forgejo Runner**: настроенный и запущенный runner
- **Cursor**: активная подписка с API доступом
- **Python**: 3.8+
- **Flutter**: 3.24.0+ (для web_v2)
- **Dart**: 3.0+ (для backend/common)

### Рекомендуемые ресурсы для runner

- **CPU**: 4+ cores
- **RAM**: 8+ GB
- **Disk**: 50+ GB свободного места
- **Network**: стабильное интернет соединение

## Настройка Forgejo

### 1. Включение Forgejo Actions

Отредактируйте `app.ini` вашего Forgejo сервера:

```ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org
```

Перезапустите Forgejo:

```bash
sudo systemctl restart forgejo
```

### 2. Установка Forgejo Runner

```bash
# Скачайте Forgejo Runner
wget https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64

# Переместите в /usr/local/bin
sudo mv forgejo-runner-3.3.0-linux-amd64 /usr/local/bin/forgejo-runner
sudo chmod +x /usr/local/bin/forgejo-runner

# Создайте директорию для runner
sudo mkdir -p /etc/forgejo-runner
cd /etc/forgejo-runner

# Создайте конфигурацию
sudo forgejo-runner create-runner-file

# Зарегистрируйте runner
# Получите registration token из Forgejo: Settings -> Actions -> Runners
sudo forgejo-runner register --no-interactive \
  --instance https://your-forgejo-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name ai-agent-runner \
  --labels ubuntu-latest:docker://node:16-bullseye
```

### 3. Настройка systemd service для runner

Создайте `/etc/systemd/system/forgejo-runner.service`:

```ini
[Unit]
Description=Forgejo Runner
After=network.target

[Service]
Type=simple
User=forgejo-runner
WorkingDirectory=/etc/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Запустите runner:

```bash
sudo systemctl daemon-reload
sudo systemctl enable forgejo-runner
sudo systemctl start forgejo-runner
sudo systemctl status forgejo-runner
```

## Настройка Secrets

### В Forgejo Repository

1. Перейдите в ваш репозиторий
2. Settings -> Secrets and Variables -> Actions
3. Добавьте следующие secrets:

#### Обязательные Secrets

**CURSOR_API_KEY**
- Описание: API ключ от Cursor
- Как получить:
  1. Откройте Cursor
  2. Settings (⚙️) -> Account -> API Keys
  3. Create new API key
  4. Скопируйте ключ (отобразится только один раз!)
- Пример: `sk-cursor-xxx...`

**FORGEJO_TOKEN**
- Описание: Personal Access Token для Forgejo API
- Как получить:
  1. Forgejo -> Settings -> Applications
  2. Generate New Token
  3. Выберите scopes: `repo`, `write:issue`, `write:workflow`
  4. Скопируйте token
- Пример: `ghp_xxxxx...`

#### Опциональные Secrets

**CURSOR_MODEL**
- Описание: Модель AI для использования
- По умолчанию: `claude-3-5-sonnet-20241022`
- Альтернативы: 
  - `gpt-4-turbo-preview`
  - `claude-3-opus-20240229`

**MAX_ITERATIONS**
- Описание: Максимум итераций за один запуск
- По умолчанию: `10`
- Рекомендуется: `10-20`

**MAX_RETRIES**
- Описание: Максимум попыток для задачи
- По умолчанию: `3`
- Рекомендуется: `2-5`

### Проверка Secrets

```bash
# Используйте Forgejo CLI (если установлен)
forgejo-cli secrets list --repo your-org/your-repo

# Или через curl
curl -X GET \
  "https://your-forgejo.com/api/v1/repos/your-org/your-repo/actions/secrets" \
  -H "Authorization: token YOUR_FORGEJO_TOKEN"
```

## Настройка Runners

### Runner Labels

Убедитесь что runner имеет правильные labels для workflows:

```yaml
# В .forgejo/workflows/agent-development.yml
runs-on: ubuntu-latest
```

Проверьте labels вашего runner:

```bash
forgejo-runner list
```

Если нужно, добавьте labels при регистрации:

```bash
sudo forgejo-runner register \
  --labels ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://ubuntu:22.04
```

### Docker vs Host режим

**Docker режим (рекомендуется)**
- Изолированное окружение
- Легкая очистка
- Требует Docker

**Host режим**
- Выполнение на хосте
- Быстрее
- Нужна ручная очистка

Выбор в конфигурации runner:

```yaml
# .runner файл
labels:
  - "ubuntu-latest:docker://node:16-bullseye"  # Docker mode
  - "ubuntu-latest:host"  # Host mode
```

## Cursor CLI

### Установка на Runner

Cursor CLI устанавливается автоматически в workflows, но можно предустановить:

```bash
# На машине runner
curl https://cursor.com/install -fsS | bash

# Добавьте в PATH
echo 'export PATH="$HOME/.cursor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Проверьте
cursor-agent --version
```

### Аутентификация Cursor CLI

Cursor CLI использует переменную окружения `CURSOR_API_KEY`:

```bash
export CURSOR_API_KEY="sk-cursor-xxx..."
cursor-agent -p "Test query"
```

В workflows это настроено автоматически через secrets.

### Лимиты и квоты

Cursor API имеет лимиты:

- **Free tier**: 500 requests/день
- **Pro tier**: 5000 requests/день
- **Team tier**: 20000 requests/день

Для 24/7 агентов рекомендуется **Pro или Team**.

## Тестирование

### 1. Тест Forgejo Runner

```bash
# Проверьте статус runner
sudo systemctl status forgejo-runner

# Проверьте логи
sudo journalctl -u forgejo-runner -f
```

### 2. Тест Secrets

Создайте тестовый workflow `.forgejo/workflows/test-secrets.yml`:

```yaml
name: Test Secrets

on:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Test CURSOR_API_KEY
        run: |
          if [ -z "${{ secrets.CURSOR_API_KEY }}" ]; then
            echo "❌ CURSOR_API_KEY not set"
            exit 1
          else
            echo "✅ CURSOR_API_KEY is set"
          fi          
      
      - name: Test FORGEJO_TOKEN
        run: |
          if [ -z "${{ secrets.FORGEJO_TOKEN }}" ]; then
            echo "❌ FORGEJO_TOKEN not set"
            exit 1
          else
            echo "✅ FORGEJO_TOKEN is set"
          fi          
```

Запустите через Actions -> Test Secrets -> Run workflow

### 3. Тест Cursor CLI

```yaml
name: Test Cursor CLI

on:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Cursor CLI
        run: |
          curl https://cursor.com/install -fsS | bash
          export PATH="$HOME/.cursor/bin:$PATH"
          cursor-agent --version          
      
      - name: Test Cursor Agent
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        run: |
          export PATH="$HOME/.cursor/bin:$PATH"
          cursor-agent -p "What is 2+2?"          
```

### 4. Тест Planning Agent

Запустите Planning Agent через UI:

1. Actions -> AI Agent - Planning
2. Run workflow
3. Выберите component: `web_v2`
4. Run workflow

Проверьте:
- ✅ Workflow запустился
- ✅ Cursor CLI установлен
- ✅ Planning agent выполнился
- ✅ task_list.json создан
- ✅ Issue создан
- ✅ Development workflow триггернут

## Troubleshooting

### Runner не запускается

**Проблема**: `forgejo-runner daemon` fails

**Решение**:
```bash
# Проверьте логи
sudo journalctl -u forgejo-runner -n 50

# Проверьте конфигурацию
cat /etc/forgejo-runner/.runner

# Переререгистрируйте
sudo forgejo-runner register --no-interactive \
  --instance https://your-forgejo.com \
  --token NEW_TOKEN
```

### Workflow не запускается

**Проблема**: Workflow pending forever

**Решение**:
1. Проверьте что runner запущен и online (Settings -> Actions -> Runners)
2. Проверьте labels: `runs-on` должен совпадать с runner labels
3. Проверьте логи runner: `sudo journalctl -u forgejo-runner -f`

### Cursor CLI authentication failed

**Проблема**: `Error: Invalid API key`

**Решение**:
1. Проверьте что `CURSOR_API_KEY` secret настроен
2. Проверьте ключ в Cursor: Settings -> Account -> API Keys
3. Создайте новый ключ если старый истек
4. Обновите secret в Forgejo

### Python script import errors

**Проблема**: `ModuleNotFoundError: No module named 'config'`

**Решение**:
```yaml
# В workflow добавьте:
- name: Set PYTHONPATH
  run: |
    export PYTHONPATH="${{ github.workspace }}/tools/agent:$PYTHONPATH"
    echo "PYTHONPATH=$PYTHONPATH" >> $GITHUB_ENV    
```

### Git push failed

**Проблема**: `remote: Permission denied`

**Решение**:
1. Проверьте что `FORGEJO_TOKEN` имеет `repo` scope
2. Настройте git credentials в workflow:
```yaml
- name: Configure Git
  run: |
    git config --global user.name "AI Agent"
    git config --global user.email "ai-agent@mnemo-cards.com"
    git config --global credential.helper store
    echo "https://ai-agent:${{ secrets.FORGEJO_TOKEN }}@your-forgejo.com" > ~/.git-credentials    
```

### Task list JSON invalid

**Проблема**: Planning agent generates invalid JSON

**Решение**:
1. Проверьте логи planning agent
2. Валидируйте JSON вручную: `cat task_list.json | jq .`
3. Если Cursor генерирует невалидный JSON, улучшите prompt

### Disk space full on runner

**Проблема**: Runner runs out of disk space

**Решение**:
```bash
# Очистите Docker images
docker system prune -af

# Очистите старые builds
cd /etc/forgejo-runner/_work
find . -type d -mtime +7 -exec rm -rf {} +

# Настройте auto-cleanup в workflow
- name: Cleanup
  if: always()
  run: |
    docker system prune -f
    rm -rf ${{ github.workspace }}/*
```

## Мониторинг

### Forgejo Actions UI

- **Workflows**: Actions tab -> All workflows
- **Runs**: Каждый workflow run с логами
- **Runners**: Settings -> Actions -> Runners

### Логи Runner

```bash
# Real-time logs
sudo journalctl -u forgejo-runner -f

# Last 100 lines
sudo journalctl -u forgejo-runner -n 100

# Logs with errors
sudo journalctl -u forgejo-runner | grep -i error
```

### Agent State

```bash
# Web v2
cat ai_docs/agent/web_v2/agent_state.json | jq

# Backend
cat ai_docs/agent/backend/agent_state.json | jq

# Check current task
cat ai_docs/agent/web_v2/agent_state.json | jq -r '.current_task_id'
```

### Metrics

Добавьте мониторинг в workflow:

```yaml
- name: Report Metrics
  if: always()
  run: |
    echo "Workflow: ${{ github.workflow }}"
    echo "Duration: ${{ steps.agent.duration }}s"
    echo "Status: ${{ job.status }}"
    # Send to monitoring system (Prometheus, Grafana, etc.)    
```

## Best Practices

### Security

1. ✅ Используйте отдельный Forgejo token для агентов (не ваш личный)
2. ✅ Ограничьте scopes token до минимума (`repo`, `write:issue`)
3. ✅ Ротируйте API ключи регулярно (раз в 3 месяца)
4. ✅ Не логируйте secrets в workflow outputs
5. ✅ Используйте runner в изолированной среде (Docker)

### Performance

1. ✅ Кешируйте dependencies (Flutter, Dart)
2. ✅ Используйте concurrent jobs где возможно
3. ✅ Ограничьте `MAX_ITERATIONS` разумным значением (10-15)
4. ✅ Настройте timeouts для jobs (6 часов max)

### Reliability

1. ✅ Мониторьте runner uptime
2. ✅ Настройте alerts для failed workflows
3. ✅ Регулярно проверяйте agent_state.json
4. ✅ Имейте fallback план (ручная разработка)

## Дополнительные ресурсы

- [Forgejo Actions Documentation](https://forgejo.org/docs/latest/user/actions/)
- [Cursor CLI Documentation](https://cursor.com/docs/cli/headless)
- [Project README](./README.md)

---

**Последнее обновление**: 2025-11-20  
**Версия**: 1.0