cinnabarflower/mnemo_cards
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mnemo_cards/ai_docs/agent/README.md

435 lines
18 KiB
Markdown
Raw Permalink Normal View History

agent
2025-11-20 21:28:55 +00:00
# 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
Reference in a new issue Copy permalink