cinnabarflower/mnemo_cards

Fork 0

Dmitry e5729bfd25 agent

2025-11-21 00:28:55 +03:00

13 KiB

Raw Blame History

AI Agent System - Configuration Guide

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

Содержание

Требования
Настройка Forgejo
Настройка Secrets
Настройка Runners
Cursor CLI
Тестирование
Troubleshooting

Требования

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

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

Настройка Forgejo

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

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

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

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

sudo systemctl restart forgejo

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

# Скачайте 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:

[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:

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

Настройка Secrets

В Forgejo Repository

Перейдите в ваш репозиторий
Settings -> Secrets and Variables -> Actions
Добавьте следующие 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

# Используйте 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:

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

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

forgejo-runner list

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

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:

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

Cursor CLI

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

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

# На машине 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:

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

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

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

2. Тест Secrets

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

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

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:

Actions -> AI Agent - Planning
Run workflow
Выберите component: web_v2
Run workflow

Проверьте:

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

Troubleshooting

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

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

Решение:

# Проверьте логи
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

Решение:

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

Cursor CLI authentication failed

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

Решение:

Проверьте что CURSOR_API_KEY secret настроен
Проверьте ключ в Cursor: Settings -> Account -> API Keys
Создайте новый ключ если старый истек
Обновите secret в Forgejo

Python script import errors

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

Решение:

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

Git push failed

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

Решение:

Проверьте что FORGEJO_TOKEN имеет repo scope
Настройте git credentials в workflow:

- 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

Решение:

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

Disk space full on runner

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

Решение:

# Очистите 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

# 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

# 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:

- 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

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

Performance

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

Reliability

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

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

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

13 KiB Raw Blame History Unescape Escape

AI Agent System - Configuration Guide

Содержание

Требования

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

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

Настройка Forgejo

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

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

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

Настройка Secrets

В Forgejo Repository

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

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

Проверка Secrets

Настройка Runners

Runner Labels

Docker vs Host режим

Cursor CLI

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

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

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

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

1. Тест Forgejo Runner

2. Тест Secrets

3. Тест Cursor CLI

4. Тест Planning Agent

Troubleshooting

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

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

Cursor CLI authentication failed

Python script import errors

Git push failed

Task list JSON invalid

Disk space full on runner

Мониторинг

Forgejo Actions UI

Логи Runner

Agent State

Metrics

Best Practices

Security

Performance

Reliability

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

13 KiB

Raw Blame History