mnemo_cards/ai_docs/agent

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

# Установка 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

# Установка 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 или проверьте:

# Проверьте что 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

Система поддерживает параллельную работу нескольких агентов:

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

Мониторинг и отладка

Просмотр состояния агента

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

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

Просмотр текущих задач

# 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 будет краткий отчет

Ручной запуск на локальной машине

# Установите переменные окружения
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

# 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

# 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"]}'

Дополнительная информация

• Конфигурация - детальная настройка системы для Forgejo
• Forgejo Actions Docs - документация Forgejo Actions
• Cursor CLI Docs - документация Cursor CLI
• Development Prompt - инструкции для разработки
• Planning Prompt - инструкции для планирования

Контакты и поддержка

При проблемах:

1. Проверьте логи в Actions
2. Посмотрите agent_state.json
3. Создайте issue с тегом ai-agent

---

Версия: 1.0
Дата: 2025-11-20
Powered by: Cursor CLI + Claude Sonnet 4.5