309 lines
11 KiB
Markdown
309 lines
11 KiB
Markdown
# AI Agent 24/7 Automation System - Summary
|
||
|
||
## Что создано
|
||
|
||
Полноценная система автоматизированной разработки с использованием AI агентов для Forgejo.
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Forgejo Actions (Workflows) │
|
||
├─────────────────────────────────────────┤
|
||
│ │
|
||
│ Planning Agent → Development Agent │
|
||
│ ↓ ↓ │
|
||
│ Task List → Code Changes │
|
||
│ ↓ │
|
||
│ Test & Deploy │
|
||
│ │
|
||
└─────────────────────────────────────────┘
|
||
↓
|
||
Cursor CLI (AI Provider)
|
||
↓
|
||
Claude Sonnet 4.5
|
||
```
|
||
|
||
## Созданные файлы
|
||
|
||
### 📁 Workflows (3 файла)
|
||
|
||
1. **`.github/workflows/agent-planning.yml`**
|
||
- Запускается вручную (workflow_dispatch)
|
||
- Анализирует проект
|
||
- Создает task_list.json
|
||
- Создает issue с summary
|
||
- Триггерит development workflow
|
||
|
||
2. **`.github/workflows/agent-development.yml`**
|
||
- Читает задачи из task_list.json
|
||
- Использует Cursor CLI для написания кода
|
||
- Запускает тесты
|
||
- Делает коммиты
|
||
- Цикл до завершения всех задач (макс 10 итераций, 6 часов)
|
||
|
||
3. **`.github/workflows/agent-test-deploy.yml`**
|
||
- Триггерится автоматически после push
|
||
- Определяет измененные компоненты
|
||
- Запускает analyze + tests для каждого
|
||
- Готовит к деплою если тесты прошли
|
||
- Создает issue если тесты не прошли
|
||
|
||
### 🐍 Python Scripts (5 файлов)
|
||
|
||
1. **`tools/agent/config.py`** (124 строки)
|
||
- Конфигурация для каждого компонента
|
||
- Пути к файлам состояния
|
||
- Команды для тестов/линтера/сборки
|
||
|
||
2. **`tools/agent/task_manager.py`** (334 строки)
|
||
- Класс `Task` - представление задачи
|
||
- Класс `AgentState` - состояние агента
|
||
- Класс `TaskManager` - работа с задачами и состоянием
|
||
- Класс `GlobalLock` - глобальная блокировка для shared resources
|
||
|
||
3. **`tools/agent/cursor_cli_wrapper.py`** (300 строк)
|
||
- Wrapper для Cursor CLI
|
||
- Парсинг stream-json output
|
||
- Отслеживание прогресса (tool calls, files modified)
|
||
- Обработка ошибок
|
||
|
||
4. **`tools/agent/agent_orchestrator.py`** (423 строки)
|
||
- Главный оркестратор development цикла
|
||
- Чтение задач
|
||
- Выполнение через Cursor CLI
|
||
- Запуск тестов
|
||
- Создание коммитов
|
||
- Обработка ретраев
|
||
|
||
5. **`tools/agent/planning_agent.py`** (334 строки)
|
||
- Planning агент
|
||
- Анализ текущего состояния проекта
|
||
- Генерация task_list.json через Cursor CLI
|
||
- Валидация JSON
|
||
- Коммит task list
|
||
|
||
### 📝 Prompts (2 файла)
|
||
|
||
1. **`ai_docs/agent/prompts/development_prompt.md`** (~400 строк)
|
||
- Инструкции для development агента
|
||
- Code standards (Clean Architecture, yx_state)
|
||
- Примеры кода
|
||
- Testing guidelines
|
||
- DO/DON'T список
|
||
|
||
2. **`ai_docs/agent/prompts/planning_prompt.md`** (~300 строк)
|
||
- Инструкции для planning агента
|
||
- Формат task list
|
||
- Priority guidelines
|
||
- Acceptance criteria examples
|
||
- Task ordering strategy
|
||
|
||
### 📊 State Files (7 файлов)
|
||
|
||
1. **`ai_docs/agent/web_v2/task_list.json`** - задачи для web_v2
|
||
2. **`ai_docs/agent/web_v2/agent_state.json`** - состояние агента web_v2
|
||
3. **`ai_docs/agent/backend/task_list.json`** - задачи для backend
|
||
4. **`ai_docs/agent/backend/agent_state.json`** - состояние агента backend
|
||
5. **`ai_docs/agent/common/task_list.json`** - задачи для common
|
||
6. **`ai_docs/agent/common/agent_state.json`** - состояние агента common
|
||
7. **`ai_docs/agent/global_lock.json`** - глобальная блокировка
|
||
|
||
### 📚 Documentation (4 файла)
|
||
|
||
1. **`ai_docs/agent/README.md`** (~600 строк)
|
||
- Полная документация системы
|
||
- Архитектура
|
||
- Как работают агенты
|
||
- Multi-agent support
|
||
- Мониторинг и отладка
|
||
- Best practices
|
||
- Примеры использования
|
||
|
||
2. **`ai_docs/agent/CONFIGURATION.md`** (~500 строк)
|
||
- Детальная конфигурация для Forgejo
|
||
- Настройка Forgejo Runner
|
||
- Настройка secrets
|
||
- Cursor CLI setup
|
||
- Troubleshooting
|
||
- Мониторинг
|
||
- Security best practices
|
||
|
||
3. **`ai_docs/agent/FORGEJO_SETUP.md`** (~400 строк)
|
||
- Пошаговая инструкция на 15-30 минут
|
||
- Настройка Forgejo Actions
|
||
- Установка runner
|
||
- Создание secrets
|
||
- Первый запуск
|
||
- Checklist проверки
|
||
|
||
4. **`ai_docs/agent/QUICKSTART.md`** (~200 строк)
|
||
- Быстрый старт за 5 минут
|
||
- Основные команды
|
||
- Структура проекта
|
||
- Troubleshooting
|
||
- Советы
|
||
|
||
## Ключевые особенности
|
||
|
||
### ✅ Multi-Agent Support
|
||
|
||
- Параллельная работа нескольких агентов
|
||
- Каждый агент работает над своим компонентом (web_v2, backend, common)
|
||
- Per-component locking
|
||
- Global lock для shared resources (mnemo_cards_common)
|
||
|
||
### ✅ Cursor CLI Integration
|
||
|
||
- Использует Cursor CLI вместо прямых API вызовов
|
||
- Автоматическая оптимизация контекста
|
||
- Уважает .cursorrules
|
||
- Stream-json для отслеживания прогресса
|
||
|
||
### ✅ Forgejo Native
|
||
|
||
- Полностью адаптировано под Forgejo
|
||
- Используется Forgejo API для issues и workflow triggers
|
||
- Работает с Forgejo Runner
|
||
- Без зависимостей от GitHub
|
||
|
||
### ✅ Safety & Limits
|
||
|
||
- Максимум 10 итераций за запуск
|
||
- Timeout 6 часов
|
||
- Максимум 3 ретрая для задачи
|
||
- Автоматический git pull перед коммитом
|
||
- Stale lock detection (2 часа)
|
||
|
||
### ✅ Autonomous Operation
|
||
|
||
- Агенты работают полностью автономно
|
||
- Не требуют вмешательства человека
|
||
- Автоматический retry при ошибках
|
||
- Создание issues при критических ошибках
|
||
|
||
## Workflow процесс
|
||
|
||
### Planning Agent
|
||
|
||
1. **Trigger**: Вручную через UI или API
|
||
2. **Input**: tasks.md, workflow_state.md, agent_state.json
|
||
3. **Process**:
|
||
- Cursor CLI анализирует проект
|
||
- Генерирует task_list.json
|
||
4. **Output**:
|
||
- Обновленный task_list.json
|
||
- GitHub issue с summary
|
||
- Триггер development workflow
|
||
|
||
### Development Agent
|
||
|
||
1. **Trigger**: Автоматически после planning или вручную
|
||
2. **Input**: task_list.json
|
||
3. **Process**:
|
||
- Цикл по задачам (по приоритету)
|
||
- Для каждой задачи:
|
||
- Cursor CLI пишет код
|
||
- Запускаются тесты
|
||
- При успехе: коммит + next task
|
||
- При ошибке: retry до 3 раз
|
||
4. **Output**:
|
||
- Git commits с изменениями
|
||
- Обновленный agent_state.json
|
||
- Issues для failed tasks
|
||
|
||
### Test & Deploy
|
||
|
||
1. **Trigger**: Автоматически после push
|
||
2. **Input**: Git diff
|
||
3. **Process**:
|
||
- Определить измененные компоненты
|
||
- Для каждого: analyze + test
|
||
4. **Output**:
|
||
- Test reports
|
||
- Deployment (если тесты прошли)
|
||
- Issues (если тесты не прошли)
|
||
|
||
## Требования
|
||
|
||
### Обязательные
|
||
|
||
- **Forgejo**: 1.20+ с Actions
|
||
- **Forgejo Runner**: установлен и запущен
|
||
- **Cursor**: активная подписка + API key
|
||
- **Python**: 3.8+
|
||
- **Flutter**: 3.24.0+ (для web_v2)
|
||
- **Dart**: 3.0+ (для backend/common)
|
||
|
||
### Secrets
|
||
|
||
- `CURSOR_API_KEY` - API ключ от Cursor
|
||
- `FORGEJO_TOKEN` - Personal Access Token для Forgejo
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Установите 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
|
||
sudo forgejo-runner register --instance https://your-forgejo.com --token TOKEN
|
||
sudo forgejo-runner daemon
|
||
```
|
||
|
||
### 2. Добавьте Secrets
|
||
|
||
Repository -> Settings -> Secrets and Variables -> Actions
|
||
|
||
- `CURSOR_API_KEY`
|
||
- `FORGEJO_TOKEN`
|
||
|
||
### 3. Запустите Planning
|
||
|
||
Actions -> AI Agent - Planning -> Run workflow -> web_v2
|
||
|
||
**Готово!** Агент начнет работу.
|
||
|
||
## Документация
|
||
|
||
- **Быстрый старт**: [QUICKSTART.md](./ai_docs/agent/QUICKSTART.md)
|
||
- **Полная настройка**: [FORGEJO_SETUP.md](./ai_docs/agent/FORGEJO_SETUP.md)
|
||
- **Конфигурация**: [CONFIGURATION.md](./ai_docs/agent/CONFIGURATION.md)
|
||
- **Документация**: [README.md](./ai_docs/agent/README.md)
|
||
|
||
## Статистика
|
||
|
||
- **Всего файлов**: 21
|
||
- **Python код**: ~1500 строк
|
||
- **Workflows**: ~500 строк
|
||
- **Prompts**: ~700 строк
|
||
- **Documentation**: ~1700 строк
|
||
- **Общий объем**: ~4400 строк кода и документации
|
||
|
||
## Возможности расширения
|
||
|
||
### В будущем можно добавить:
|
||
|
||
- [ ] Telegram уведомления о прогрессе
|
||
- [ ] Dashboard для мониторинга
|
||
- [ ] Автоматические расписания (cron triggers)
|
||
- [ ] Metrics и аналитика (сколько задач выполнено, время и т.д.)
|
||
- [ ] Интеграция с CI/CD для автодеплоя
|
||
- [ ] A/B тестирование разных AI моделей
|
||
- [ ] Система приоритетов на основе бизнес-метрик
|
||
- [ ] Автоматический rollback при критических ошибках
|
||
|
||
## Лицензия
|
||
|
||
Использует:
|
||
- **Cursor CLI**: Коммерческая лицензия Cursor
|
||
- **Forgejo**: MIT License
|
||
- **Остальной код**: Собственная разработка для проекта mnemo_cards
|
||
|
||
---
|
||
|
||
**Создано**: 2025-11-20
|
||
**Версия**: 1.0
|
||
**Powered by**: Cursor CLI + Claude Sonnet 4.5 + Forgejo Actions
|
||
|