434 lines
18 KiB
Markdown
434 lines
18 KiB
Markdown
# AI Agent 24/7 Automation System
|
||
|
||
Автоматизированная система разработки с использованием AI агентов, которые работают круглосуточно над проектом mnemo_cards.
|
||
|
||
## Обзор
|
||
|
||
Система состоит из трех типов агентов:
|
||
|
||
1. **Planning Agent** - анализирует проект и создает список задач
|
||
2. **Development Agent** - читает задачи, пишет код, делает коммиты
|
||
3. **Test & Deploy** - тестирует изменения и деплоит на staging
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ GitHub/Forgejo Actions │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Planning │───▶│ Development │───▶│ Test/Deploy │ │
|
||
│ │ Agent │ │ Agent │ │ │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ Cursor CLI (AI Provider) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌────────────────────────┐
|
||
│ Project Repository │
|
||
│ - mnemo_cards_web_v2 │
|
||
│ - mnemo_cards_backend │
|
||
│ - mnemo_cards_common │
|
||
└────────────────────────┘
|
||
```
|
||
|
||
## Компоненты
|
||
|
||
### 1. Task Management
|
||
|
||
Файлы состояния для каждого компонента:
|
||
|
||
```
|
||
ai_docs/agent/
|
||
├── 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 # Глобальная блокировка
|
||
```
|
||
|
||
### 2. Python Scripts
|
||
|
||
Оркестрация и управление агентами:
|
||
|
||
```
|
||
tools/agent/
|
||
├── config.py # Конфигурация
|
||
├── task_manager.py # Менеджер задач
|
||
├── cursor_cli_wrapper.py # Wrapper для Cursor CLI
|
||
├── agent_orchestrator.py # Главный оркестратор (development)
|
||
└── planning_agent.py # Planning агент
|
||
```
|
||
|
||
### 3. Prompts
|
||
|
||
Инструкции для агентов:
|
||
|
||
```
|
||
ai_docs/agent/prompts/
|
||
├── development_prompt.md # Инструкции для development агента
|
||
└── planning_prompt.md # Инструкции для planning агента
|
||
```
|
||
|
||
### 4. GitHub Actions Workflows
|
||
|
||
```
|
||
.github/workflows/
|
||
├── agent-planning.yml # Planning workflow
|
||
├── agent-development.yml # Development workflow
|
||
└── agent-test-deploy.yml # Test & Deploy workflow
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Настройка Forgejo Runner
|
||
|
||
```bash
|
||
# Установка 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
|
||
|
||
# Регистрация 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
|
||
|
||
# Запуск runner (или через systemd)
|
||
sudo forgejo-runner daemon
|
||
```
|
||
|
||
### 2. Настройка Cursor CLI
|
||
|
||
```bash
|
||
# Установка Cursor CLI (на машине runner или автоматически в workflows)
|
||
curl https://cursor.com/install -fsS | bash
|
||
|
||
# Получение API ключа
|
||
# 1. Откройте Cursor
|
||
# 2. Settings -> Account -> API Keys
|
||
# 3. Create new API key
|
||
```
|
||
|
||
### 3. Настройка Secrets в Forgejo
|
||
|
||
Добавьте следующие secrets в настройках репозитория:
|
||
**Repository Settings -> Secrets and Variables -> Actions**
|
||
|
||
- `CURSOR_API_KEY` - API ключ от Cursor (обязательно)
|
||
- `FORGEJO_TOKEN` - Personal Access Token для Forgejo API (обязательно, scopes: repo, write:issue, write:workflow)
|
||
- `CURSOR_MODEL` - Модель AI (опционально, по умолчанию claude-3-5-sonnet-20241022)
|
||
- `MAX_ITERATIONS` - Максимум итераций (опционально, по умолчанию 10)
|
||
- `MAX_RETRIES` - Максимум попыток (опционально, по умолчанию 3)
|
||
|
||
### 3. Запуск Planning Agent
|
||
|
||
1. Перейдите в **Actions** в вашем репозитории
|
||
2. Выберите workflow **"AI Agent - Planning"**
|
||
3. Нажмите **"Run workflow"**
|
||
4. Выберите компонент (web_v2, backend, или common)
|
||
5. Нажмите **"Run workflow"**
|
||
|
||
Planning agent:
|
||
- Проанализирует текущее состояние проекта
|
||
- Создаст список задач в `ai_docs/agent/{component}/task_list.json`
|
||
- Создаст issue с summary
|
||
- Автоматически запустит Development Agent
|
||
|
||
### 4. Проверка настройки
|
||
|
||
Создайте тестовый workflow или проверьте:
|
||
|
||
```bash
|
||
# Проверьте что runner запущен
|
||
sudo systemctl status forgejo-runner
|
||
|
||
# Проверьте secrets через Forgejo UI
|
||
# Repository -> Settings -> Secrets and Variables -> Actions
|
||
|
||
# Проверьте что .github/workflows/ содержит файлы
|
||
ls -la .github/workflows/
|
||
```
|
||
|
||
### 5. Запуск Development Agent
|
||
|
||
Development agent запускается автоматически после Planning Agent, или можно запустить вручную:
|
||
|
||
1. Actions -> **"AI Agent - Development"**
|
||
2. Run workflow -> выбрать компонент
|
||
3. Agent начнет работу над задачами
|
||
|
||
**Примечание**: Убедитесь что Forgejo Runner запущен и online перед запуском workflows!
|
||
|
||
## Как это работает
|
||
|
||
### Planning Agent Workflow
|
||
|
||
1. **Анализ**: Читает `tasks.md`, `workflow_state.md`, текущий `task_list.json`
|
||
2. **Генерация**: Использует Cursor CLI для создания нового task list
|
||
3. **Валидация**: Проверяет корректность JSON и структуры задач
|
||
4. **Коммит**: Сохраняет task_list.json в репозиторий
|
||
5. **Запуск**: Триггерит Development Agent
|
||
|
||
### Development Agent Workflow
|
||
|
||
1. **Инициализация**: Загружает task list и agent state
|
||
2. **Выбор задачи**: Берет следующую pending задачу по приоритету
|
||
3. **Блокировка**: Проверяет, нужна ли глобальная блокировка
|
||
4. **Выполнение**:
|
||
- Использует Cursor CLI для написания кода
|
||
- Запускает линтер
|
||
- Запускает тесты
|
||
- Делает коммит с описанием изменений
|
||
5. **Обновление**: Обновляет статус задачи и agent state
|
||
6. **Повтор**: Берет следующую задачу или завершается
|
||
|
||
### Test & Deploy Workflow
|
||
|
||
1. **Триггер**: Автоматически запускается после коммитов
|
||
2. **Обнаружение**: Определяет, какие компоненты изменились
|
||
3. **Тестирование**:
|
||
- Запускает flutter/dart analyze
|
||
- Запускает тесты
|
||
- Собирает coverage
|
||
4. **Результат**:
|
||
- ✅ Если тесты прошли - готово к деплою
|
||
- ❌ Если тесты не прошли - создает issue
|
||
|
||
## Multi-Agent Support
|
||
|
||
Система поддерживает параллельную работу нескольких агентов:
|
||
|
||
```bash
|
||
# Агент 1: работает над web_v2
|
||
Actions -> Planning -> web_v2
|
||
└─> Development -> web_v2
|
||
|
||
# Агент 2: одновременно работает над backend
|
||
Actions -> Planning -> backend
|
||
└─> Development -> backend
|
||
```
|
||
|
||
### Координация агентов
|
||
|
||
- **Per-component locking**: Каждый агент блокирует только свой компонент
|
||
- **Global lock**: Если задача модифицирует `mnemo_cards_common`, берется глобальная блокировка
|
||
- **Conflict resolution**: Перед коммитом делается git pull --rebase
|
||
|
||
## Мониторинг и отладка
|
||
|
||
### Просмотр состояния агента
|
||
|
||
```bash
|
||
# Web v2
|
||
cat ai_docs/agent/web_v2/agent_state.json
|
||
|
||
# Backend
|
||
cat ai_docs/agent/backend/agent_state.json
|
||
```
|
||
|
||
### Просмотр текущих задач
|
||
|
||
```bash
|
||
# Web v2
|
||
cat ai_docs/agent/web_v2/task_list.json
|
||
|
||
# Backend
|
||
cat ai_docs/agent/backend/task_list.json
|
||
```
|
||
|
||
### Логи workflow
|
||
|
||
1. Actions -> выберите workflow run
|
||
2. Посмотрите логи каждого step
|
||
3. В summary будет краткий отчет
|
||
|
||
### Ручной запуск на локальной машине
|
||
|
||
```bash
|
||
# Установите переменные окружения
|
||
export CURSOR_API_KEY="your-key-here"
|
||
export PROJECT_ROOT="/path/to/mnemo_cards"
|
||
|
||
# Planning agent
|
||
python tools/agent/planning_agent.py web_v2
|
||
|
||
# Development agent
|
||
python tools/agent/agent_orchestrator.py web_v2
|
||
```
|
||
|
||
## Ограничения и safety
|
||
|
||
### Автоматические ограничения
|
||
|
||
- **Max iterations**: 10 итераций за один запуск
|
||
- **Timeout**: 6 часов на workflow run
|
||
- **Max retries**: 3 попытки на задачу
|
||
- **Stale lock**: Блокировка считается устаревшей через 2 часа
|
||
|
||
### Что агенты НЕ могут делать
|
||
|
||
❌ Удалять .git директорию
|
||
❌ Force push
|
||
❌ Модифицировать production secrets
|
||
❌ Деплоить на production (только staging)
|
||
❌ Удалять файлы без причины
|
||
|
||
### Безопасность
|
||
|
||
- Все коммиты проверяются через Test workflow
|
||
- Агенты не имеют доступа к production secrets
|
||
- Изменения можно ревьюить через Git history
|
||
- Можно откатить любой коммит
|
||
|
||
## Troubleshooting
|
||
|
||
### Агент не запускается
|
||
|
||
1. Проверьте, что `CURSOR_API_KEY` настроен в Secrets
|
||
2. Проверьте, что Cursor CLI установлен (в логах workflow)
|
||
3. Проверьте, что task_list.json существует и валиден
|
||
|
||
### Тесты не проходят
|
||
|
||
1. Агент попробует исправить 3 раза
|
||
2. После 3 попыток создается issue
|
||
3. Агент переходит к следующей задаче
|
||
|
||
### Агент "завис"
|
||
|
||
1. Agent state показывает "in_progress" более 2 часов
|
||
2. Запустите новый workflow - он сбросит состояние
|
||
3. Или вручную отредактируйте agent_state.json
|
||
|
||
### Конфликты коммитов
|
||
|
||
1. Агент делает `git pull --rebase` перед коммитом
|
||
2. Если конфликт - задача помечается skipped
|
||
3. Planning agent переназначит задачу позже
|
||
|
||
## Best Practices
|
||
|
||
### Для человека-разработчика
|
||
|
||
1. ✅ Обновляйте `tasks.md` с новыми фичами
|
||
2. ✅ Ревьюите коммиты от агентов
|
||
3. ✅ Запускайте Planning Agent раз в неделю
|
||
4. ❌ Не редактируйте task_list.json вручную (используйте tasks.md)
|
||
5. ❌ Не коммитьте в те же файлы, над которыми работает агент
|
||
|
||
### Для Planning Agent
|
||
|
||
- Создавайте задачи на 2-8 часов работы
|
||
- Разбивайте большие фичи на подзадачи
|
||
- Указывайте четкие acceptance criteria
|
||
- Правильно выставляйте dependencies
|
||
|
||
### Для Development Agent
|
||
|
||
- Всегда пишите тесты
|
||
- Следуйте существующим паттернам кода
|
||
- Не оставляйте TODOs
|
||
- Делайте атомарные коммиты
|
||
|
||
## Примеры использования
|
||
|
||
### Сценарий 1: Добавление новой фичи
|
||
|
||
1. Добавьте описание фичи в `mnemo_cards_web_v2/tasks.md`
|
||
2. Запустите Planning Agent для web_v2
|
||
3. Planning Agent создаст задачи
|
||
4. Development Agent автоматически начнет работу
|
||
5. Мониторьте прогресс в Actions
|
||
6. Ревьюйте коммиты от агента
|
||
|
||
### Сценарий 2: Исправление багов
|
||
|
||
1. Создайте issue с описанием бага
|
||
2. Запустите Planning Agent
|
||
3. Planning Agent добавит задачу в task list
|
||
4. Development Agent исправит баг
|
||
5. Test workflow проверит, что баг исправлен
|
||
|
||
### Сценарий 3: Рефакторинг
|
||
|
||
1. Опишите план рефакторинга в tasks.md
|
||
2. Запустите Planning Agent
|
||
3. Agent создаст задачи для рефакторинга
|
||
4. Development Agent выполнит рефакторинг поэтапно
|
||
5. Все тесты должны продолжать проходить
|
||
|
||
## Особенности Forgejo
|
||
|
||
### Отличия от GitHub Actions
|
||
|
||
1. **API endpoints**: Используется Forgejo API вместо GitHub API
|
||
2. **Actions**: Некоторые GitHub Actions могут не работать, используются альтернативы
|
||
3. **Secrets**: Настраиваются через Forgejo UI (Settings -> Secrets and Variables -> Actions)
|
||
4. **Runner**: Требует установки и настройки Forgejo Runner
|
||
5. **Workflows**: Синтаксис совместим, но используется `.github/workflows/` (не `.forgejo/workflows/`)
|
||
|
||
### Forgejo API для триггера workflows
|
||
|
||
```bash
|
||
# Trigger Planning Agent
|
||
curl -X POST \
|
||
"https://your-forgejo.com/api/v1/repos/user/repo/actions/workflows/agent-planning.yml/dispatches" \
|
||
-H "Authorization: token YOUR_FORGEJO_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"ref":"master","inputs":{"component":"web_v2"}}'
|
||
|
||
# Trigger Development Agent
|
||
curl -X POST \
|
||
"https://your-forgejo.com/api/v1/repos/user/repo/actions/workflows/agent-development.yml/dispatches" \
|
||
-H "Authorization: token YOUR_FORGEJO_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"ref":"master","inputs":{"component":"web_v2"}}'
|
||
```
|
||
|
||
### Создание Issues через API
|
||
|
||
```bash
|
||
# Create issue
|
||
curl -X POST \
|
||
"https://your-forgejo.com/api/v1/repos/user/repo/issues" \
|
||
-H "Authorization: token YOUR_FORGEJO_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"title":"Issue title","body":"Issue body","labels":["ai-agent"]}'
|
||
```
|
||
|
||
## Дополнительная информация
|
||
|
||
- [Конфигурация](./CONFIGURATION.md) - детальная настройка системы для Forgejo
|
||
- [Forgejo Actions Docs](https://forgejo.org/docs/latest/user/actions/) - документация Forgejo Actions
|
||
- [Cursor CLI Docs](https://cursor.com/docs/cli/headless) - документация Cursor CLI
|
||
- [Development Prompt](./prompts/development_prompt.md) - инструкции для разработки
|
||
- [Planning Prompt](./prompts/planning_prompt.md) - инструкции для планирования
|
||
|
||
## Контакты и поддержка
|
||
|
||
При проблемах:
|
||
1. Проверьте логи в Actions
|
||
2. Посмотрите agent_state.json
|
||
3. Создайте issue с тегом `ai-agent`
|
||
|
||
---
|
||
|
||
**Версия:** 1.0
|
||
**Дата:** 2025-11-20
|
||
**Powered by:** Cursor CLI + Claude Sonnet 4.5
|
||
|