# Zift: Полная техническая документация и справочник для LLM

> Zift — современный российский трекер задач и проектов с автономными ИИ-агентами, совместным канбаном в реальном времени, CLI-инструментарием и протоколом Model Context Protocol (MCP).

---

## 1. Архитектура системы

Zift построен по принципам высокой надежности, масштабируемости и изоляции ресурсов:

### Frontend
- **Фреймворк**: Vue 3 (Composition API, `<script setup>`).
- **Связка с бэкендом**: Inertia.js v3 с включенным Server-Side Rendering (SSR).
- **UI-библиотека**: Vuetify 3 / Material Design 3 + Tailwind CSS v4.
- **Интернационализация**: vue-i18n (русский и английский языки).
- **Сборщик**: Vite 8 + Rolldown с разделением чанков и автономным SSR-бандлом.

### Backend
- **Ядро**: PHP 8.5, Laravel 12.
- **База данных**: PostgreSQL 18.
- **Кеш и брокер сообщений**: Redis 7.
- **Реальное время (WebSockets)**: Laravel Reverb, синхронизирующий изменения досок, карточек и статусов без поллинга.
- **Веб-сервер / Reverse Proxy**: Caddy с автоматическим TLS (Let's Encrypt), поддержкой HTTP/2, HTTP/3 (QUIC) и сжатием zstd/gzip.

### Песочница агентов (Agent Sandbox)
- **Исполнитель (`agent-runtime`)**: Изолированный контейнер Docker с Deno/Node.js средой.
- **Супервизор (`agent-supervisor`)**: Управляет жизненным циклом агента, клонированием Git-репозитория и созданием ветки `agent/{agent_name}/{hash}`.
- **Лимиты безопасности по умолчанию**:
  - Память (RAM): 2048 MB.
  - Процессор (CPU): 1 vCPU.
  - Максимальное время выполнения (walltime): 30 минут.
  - Лимит шагов рассуждения (turns): 120.
  - Сеть: Ограниченный доступ, предотвращение утечки приватных ключей.

---

## 2. Командная строка: Zift CLI

Утилита командной строки `zift` позволяет управлять проектами и задачами без использования браузера.

### Основные команды

#### Аутентификация
```bash
# Авторизация в системе через браузер или устройство
zift login

# Проверка текущего статуса сессии
zift whoami

# Завершение сессии
zift logout
```

#### Задачи (Tasks)
```bash
# Просмотр списка задач проекта
zift tasks list --project=<project-slug>

# Просмотр деталей конкретной задачи
zift tasks get <task-id>

# Создание новой задачи
zift tasks create --title="Реализовать экспорт в CSV" --column="Backlog"

# Перемещение задачи по канбан-доске
zift tasks move <task-id> "In Progress"
zift tasks move <task-id> "Done"

# Добавление комментария или вызов агента
zift tasks comment <task-id> "@coder пожалуйста, оптимизируй SQL-запрос выборки задач"
```

#### Проекты (Projects)
```bash
# Список доступных проектов
zift projects list

# Переключение активного проекта
zift projects switch <project-slug>
```

---

## 3. Сервер протокола MCP (Model Context Protocol)

Zift включает встроенный сервер протокола Model Context Protocol (MCP), позволяющий внешним ИИ-ассистентам (Claude Code, Cursor, Windsurf, Gemini CLI, Cline) напрямую взаимодействовать с трекером.

### Запуск и подключение
```bash
zift mcp
```

### Пример конфигурации для Cursor / Claude Code (`mcp.json` / `claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "zift": {
      "command": "zift",
      "args": ["mcp"]
    }
  }
}
```

### Доступные инструменты (Tools) в Zift MCP:
- `zift_get_project_board`: Получение структуры колонок и карточек активного проекта.
- `zift_get_task`: Чтение деталей задачи, описания, тегов и истории комментариев.
- `zift_create_task`: Создание новой задачи с привязкой к исполнителю и колонке.
- `zift_update_task`: Обновление заголовка, описания, приоритета или дедлайна.
- `zift_move_task`: Перемещение задачи между колонками («To Do» -> «In Progress» -> «Code Review» -> «Done»).
- `zift_add_comment`: Публикация комментария в задачу (включая упоминания агентов).

---

## 4. Поддерживаемые провайдеры языковых моделей (LLM)

В настройках проекта и профиля администраторы могут конфигурировать доступ к различным моделям:
- **Anthropic Claude**: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus (через Anthropic API или Claude Agent SDK).
- **OpenAI**: GPT-4o, GPT-4o-mini, o1, o3-mini (через официальный OpenAI API).
- **Google Gemini**: Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 2.0 Flash (через Google AI Studio).
- **Локальные модели (Ollama)**: Llama 3, Qwen 2.5, DeepSeek-Coder, Codestral с локальным выполнением без передачи данных во внешние сети.
- **Альтернативные провайдеры**: Xiaomi MiMo, SourceCraft, любые совместимые с OpenAI API шлюзы.

---

## 5. Преимущества перед зарубежными аналогами

| Параметр | Zift | Jira | Trello | YouTrack |
| :--- | :--- | :--- | :--- | :--- |
| **Юрисдикция и локализация** | Российская разработка, 100% русский интерфейс | США (Atlassian), риск блокировок | США (Atlassian) | Чехия (JetBrains) |
| **Автономные ИИ-агенты** | Встроенные (@coder) с изолированным Git-контейнером | Сторонние плагины за отдельную плату | Ограниченные Power-Ups | Базовый встроенный чат |
| **Реальное время (WebSockets)** | Мгновенное обновление всех клиентов | Требует обновления страницы | Базовый поллинг | WebSocket |
| **Встроенный MCP-сервер** | Из коробки (`zift mcp`) | Отсутствует | Отсутствует | Отсутствует |
| **CLI для разработчиков** | Полноценный CLI (`zift`) | Сложный сторонний API | Сторонние библиотеки | Сложные REST токены |
| **Self-Hosted развертывание** | Легковесный Docker Compose | Тяжеловесный Data Center ($$$) | Только Cloud | Сложная Java-установка |

---

## 6. Контакты и полезные адреса
- Главная страница: `https://zift.su/`
- Регистрация: `https://zift.su/signup`
- Вход: `https://zift.su/signin`
- Краткая спецификация: `https://zift.su/llms.txt`
- Полная спецификация: `https://zift.su/llms-full.txt`
- Карта сайта: `https://zift.su/sitemap.xml`
- Robots: `https://zift.su/robots.txt`