mnemo_cards/ai_docs/agent/QUICKSTART.md

# AI Agent System - Quick Start

Быстрый старт для запуска AI агентов на Forgejo.

## 🚀 За 5 минут

### 1. Установите Forgejo Runner

```bash
wget https://code.forgejo.org/forgejo/runner/releases/download/v3.3.0/forgejo-runner-3.3.0-linux-amd64
sudo mv forgejo-runner-3.3.0-linux-amd64 /usr/local/bin/forgejo-runner
sudo chmod +x /usr/local/bin/forgejo-runner

# Получите token: Repository -> Settings -> Actions -> Runners -> Create
sudo forgejo-runner register --instance https://your-forgejo.com --token YOUR_TOKEN

# Запустите
sudo forgejo-runner daemon
```

### 2. Добавьте Secrets

**Repository -> Settings -> Secrets and Variables -> Actions**

1. `CURSOR_API_KEY` = ваш Cursor API key (Cursor -> Settings -> Account -> API Keys)
2. `FORGEJO_TOKEN` = ваш Forgejo Personal Access Token (Settings -> Applications)

### 3. Запустите Planning Agent

**Actions -> AI Agent - Planning -> Run workflow**

Выберите component: `web_v2`

**Готово!** 🎉

Агент:
- Проанализирует проект
- Создаст task list
- Автоматически запустит Development Agent
- Начнет писать код

---

## 📚 Подробная документация

- [Полная настройка для Forgejo](./FORGEJO_SETUP.md) - пошаговая инструкция 15-30 мин
- [Детальная конфигурация](./CONFIGURATION.md) - все настройки и troubleshooting
- [README](./README.md) - архитектура и как это работает

## 🎯 Основные команды

### Проверка статуса runner

```bash
sudo systemctl status forgejo-runner
```

### Просмотр 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
```

### Триггер через API

```bash
curl -X POST \
  "https://your-forgejo.com/api/v1/repos/user/repo/actions/workflows/agent-planning.yml/dispatches" \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"master","inputs":{"component":"web_v2"}}'
```

## 🔧 Структура проекта

```
ai_docs/agent/
├── README.md                          # Полная документация
├── QUICKSTART.md                      # Этот файл
├── FORGEJO_SETUP.md                   # Пошаговая настройка
├── CONFIGURATION.md                   # Детальная конфигурация
├── web_v2/
│   ├── task_list.json                 # Список задач
│   └── agent_state.json               # Состояние агента
├── backend/
│   ├── task_list.json
│   └── agent_state.json
├── common/
│   ├── task_list.json
│   └── agent_state.json
├── global_lock.json                   # Глобальная блокировка
└── prompts/
    ├── development_prompt.md          # Инструкции для dev агента
    └── planning_prompt.md             # Инструкции для planning агента

.github/workflows/
├── agent-planning.yml                 # Planning workflow
├── agent-development.yml              # Development workflow
└── agent-test-deploy.yml              # Test & Deploy workflow

tools/agent/
├── config.py                          # Конфигурация
├── task_manager.py                    # Менеджер задач
├── cursor_cli_wrapper.py              # Wrapper для Cursor CLI
├── agent_orchestrator.py              # Главный оркестратор
└── planning_agent.py                  # Planning агент
```

## ⚡ Работа с несколькими компонентами

Запустите агентов параллельно:

```bash
# Planning для web_v2
Actions -> AI Agent - Planning -> web_v2

# Planning для backend (одновременно)
Actions -> AI Agent - Planning -> backend
```

Агенты работают независимо, но координируются через `global_lock.json` когда нужно.

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

### В Forgejo UI

- **Actions tab** - все workflow runs
- **Issues** - автоматические отчеты от агентов

### В командной строке

```bash
# Логи runner
sudo journalctl -u forgejo-runner -f

# Текущая задача
cat ai_docs/agent/web_v2/agent_state.json | jq -r '.current_task_id'

# Завершенные задачи
cat ai_docs/agent/web_v2/agent_state.json | jq -r '.completed_tasks[]'
```

## 🛠️ Troubleshooting

**Runner не online?**
```bash
sudo systemctl restart forgejo-runner
sudo journalctl -u forgejo-runner -n 50
```

**Workflow не запускается?**
- Проверьте что runner online: Settings -> Actions -> Runners
- Проверьте labels: должен быть `ubuntu-latest`

**Secrets не работают?**
- Проверьте названия: точно `CURSOR_API_KEY` и `FORGEJO_TOKEN`
- Перепроверьте значения
- Пересоздайте если нужно

**Подробнее**: [CONFIGURATION.md](./CONFIGURATION.md#troubleshooting)

## 💡 Советы

1. **Начните с web_v2** - самый активный компонент
2. **Проверяйте коммиты** - агент делает коммиты с описанием
3. **Ревьюйте changes** - агент может ошибаться
4. **Обновляйте tasks.md** - для новых задач
5. **Мониторьте ресурсы** - агент потребляет CPU/RAM

## 🎓 Дальше

После первого успешного запуска:

1. Почитайте [README.md](./README.md) чтобы понять как все работает
2. Настройте дополнительные параметры в [CONFIGURATION.md](./CONFIGURATION.md)
3. Запустите агентов для других компонентов (backend, common)
4. Настройте автоматические расписания (cron)

---

**Нужна помощь?** Смотрите [полную документацию](./README.md) или создайте issue.