186 lines
6.3 KiB
Markdown
186 lines
6.3 KiB
Markdown
# 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.
|
||
|