mnemo_cards/ai_docs/agent/FORGEJO_SETUP.md

# Быстрая настройка для Forgejo

Пошаговая инструкция для быстрого запуска AI Agent системы на Forgejo.

## Шаг 1: Настройка Forgejo Actions

### 1.1 Включите Actions в Forgejo

Отредактируйте `/etc/forgejo/app.ini`:

```ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org
```

Перезапустите:

```bash
sudo systemctl restart forgejo
```

### 1.2 Установите Forgejo Runner

```bash
# Скачайте 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

# Создайте директорию
sudo mkdir -p /etc/forgejo-runner
cd /etc/forgejo-runner
```

### 1.3 Получите Registration Token

1. Откройте Forgejo в браузере
2. Перейдите в ваш репозиторий
3. Settings -> Actions -> Runners
4. Нажмите "Create new Runner"
5. Скопируйте Registration Token

### 1.4 Зарегистрируйте Runner

```bash
cd /etc/forgejo-runner
sudo forgejo-runner register \
  --no-interactive \
  --instance https://your-forgejo.com \
  --token ВАШТОКЕН \
  --name ai-agent-runner \
  --labels ubuntu-latest:docker://node:16-bullseye
```

### 1.5 Создайте systemd service

```bash
sudo tee /etc/systemd/system/forgejo-runner.service > /dev/null <<EOF
[Unit]
Description=Forgejo Runner
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/etc/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Запустите
sudo systemctl daemon-reload
sudo systemctl enable forgejo-runner
sudo systemctl start forgejo-runner
```

### 1.6 Проверьте статус

```bash
sudo systemctl status forgejo-runner

# Должно быть: Active: active (running)
```

## Шаг 2: Настройка Cursor API

### 2.1 Получите API Key

1. Откройте Cursor
2. Settings (⚙️)
3. Account -> API Keys
4. "Create new API key"
5. Скопируйте ключ (показывается только один раз!)

Сохраните ключ, например: `sk-cursor-abc123...`

## Шаг 3: Настройка Secrets в Forgejo

### 3.1 Создайте Forgejo Token

1. Forgejo -> Settings -> Applications
2. Generate New Token
3. Token Name: `ai-agent-token`
4. Select Scopes:
   - ✅ `repo` (Full control of repositories)
   - ✅ `write:issue` (Create and edit issues)
   - ✅ `write:workflow` (Update workflow files)
5. Generate Token
6. Скопируйте token

### 3.2 Добавьте Secrets в Repository

1. Откройте ваш репозиторий в Forgejo
2. Settings -> Secrets and Variables -> Actions
3. Добавьте два обязательных secrets:

**Secret 1: CURSOR_API_KEY**
- Name: `CURSOR_API_KEY`
- Value: `sk-cursor-abc123...` (ваш ключ из Step 2.1)

**Secret 2: FORGEJO_TOKEN**
- Name: `FORGEJO_TOKEN`
- Value: ваш token из Step 3.1

**Optional Secret 3: CURSOR_MODEL**
- Name: `CURSOR_MODEL`
- Value: `claude-3-5-sonnet-20241022`

## Шаг 4: Проверка файлов

Убедитесь что эти файлы существуют в вашем репозитории:

```bash
ls -la .github/workflows/
# Должны быть:
# - agent-planning.yml
# - agent-development.yml
# - agent-test-deploy.yml

ls -la tools/agent/
# Должны быть:
# - config.py
# - task_manager.py
# - cursor_cli_wrapper.py
# - agent_orchestrator.py
# - planning_agent.py

ls -la ai_docs/agent/
# Должны быть:
# - web_v2/task_list.json
# - web_v2/agent_state.json
# - backend/task_list.json
# - backend/agent_state.json
# - global_lock.json
# - prompts/development_prompt.md
# - prompts/planning_prompt.md
```

## Шаг 5: Первый запуск

### 5.1 Запустите Planning Agent

1. В Forgejo откройте репозиторий
2. Перейдите на вкладку **Actions**
3. Слева выберите **"AI Agent - Planning"**
4. Справа нажмите **"Run workflow"**
5. Выберите:
   - Branch: `master`
   - Component: `web_v2`
6. Нажмите **"Run workflow"**

### 5.2 Наблюдайте за выполнением

1. Вернитесь на вкладку Actions
2. Увидите новый workflow run
3. Кликните на него
4. Смотрите логи в реальном времени

### 5.3 Проверьте результат

После завершения Planning Agent:

```bash
# Клонируйте репозиторий (если еще не клонировали)
git clone https://your-forgejo.com/user/repo.git
cd repo

# Проверьте task list
cat ai_docs/agent/web_v2/task_list.json | jq

# Должен быть JSON с задачами
```

Также:
- Должен появиться новый Issue с summary
- Должен автоматически запуститься Development Agent

### 5.4 Наблюдайте Development Agent

Development Agent запустится автоматически:

1. Actions -> "AI Agent - Development"
2. Найдите активный workflow run
3. Смотрите как агент:
   - Читает задачи
   - Пишет код
   - Запускает тесты
   - Делает коммиты

## Проверка что все работает

### ✅ Checklist

- [ ] Forgejo Actions включены (`app.ini`)
- [ ] Forgejo Runner запущен и online
- [ ] Cursor API Key получен
- [ ] Forgejo Token создан
- [ ] Оба secrets добавлены в repository
- [ ] Workflow файлы существуют в `.github/workflows/`
- [ ] Python скрипты существуют в `tools/agent/`
- [ ] State файлы существуют в `ai_docs/agent/*/`
- [ ] Planning Agent успешно запущен
- [ ] Task list JSON создан
- [ ] Development Agent запущен автоматически

### 🐛 Если что-то не работает

**Runner offline:**
```bash
sudo systemctl status forgejo-runner
sudo journalctl -u forgejo-runner -f
```

**Workflow не запускается:**
- Проверьте что runner online (Settings -> Actions -> Runners)
- Проверьте labels runner совпадают с `runs-on: ubuntu-latest`

**Secrets не работают:**
- Перепроверьте названия: `CURSOR_API_KEY` и `FORGEJO_TOKEN`
- Убедитесь что ввели правильные значения
- Попробуйте пересоздать secrets

**Python ошибки:**
- Проверьте логи workflow
- Убедитесь что все файлы в `tools/agent/` существуют
- Проверьте синтаксис Python скриптов

## Дальнейшие шаги

После успешного первого запуска:

1. **Мониторинг**: Следите за прогрессом в Actions tab
2. **Ревью**: Проверяйте коммиты от агента
3. **Настройка**: Отредактируйте `tasks.md` для новых задач
4. **Масштабирование**: Запустите агентов для других компонентов (backend, common)

## Полезные команды

```bash
# Проверка runner
sudo systemctl status forgejo-runner

# Логи runner
sudo journalctl -u forgejo-runner -f

# Проверка agent state
cat ai_docs/agent/web_v2/agent_state.json | jq

# Проверка task list
cat ai_docs/agent/web_v2/task_list.json | jq

# Триггер planning через API
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"}}'

# Список workflow runs
curl -X GET \
  "https://your-forgejo.com/api/v1/repos/user/repo/actions/runs" \
  -H "Authorization: token $FORGEJO_TOKEN"
```

## Поддержка

Если возникли проблемы:

1. Проверьте [CONFIGURATION.md](./CONFIGURATION.md) для детальной настройки
2. Посмотрите [README.md](./README.md) для полной документации
3. Проверьте логи: `sudo journalctl -u forgejo-runner -f`
4. Создайте issue в репозитории

---

**Время на настройку**: 15-30 минут  
**Сложность**: Средняя  
**Требует**: Root доступ к серверу Forgejo