mnemo_cards/ai_docs/agent/QUICKSTART.md

AI Agent System - Quick Start

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

🚀 За 5 минут

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

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 - пошаговая инструкция 15-30 мин
• Детальная конфигурация - все настройки и troubleshooting
• README - архитектура и как это работает

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

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

sudo systemctl status forgejo-runner

Просмотр agent state

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

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

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

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 агент

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

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

# 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 - автоматические отчеты от агентов

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

# Логи 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?

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

💡 Советы

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

🎓 Дальше

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

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

---

Нужна помощь? Смотрите полную документацию или создайте issue.