Skip to content

PRESENTATION_RU.md

Latest commit

 

History

History
274 lines (193 loc) · 13.3 KB

PRESENTATION_RU.md

File metadata and controls

274 lines (193 loc) · 13.3 KB

Презентация: Windows-специфичные улучшения для 1Code

Обзор проекта

Базовый репозиторий: 21st-dev/1code (оригинальный проект)
Наш форк: evgyur/1code (Windows-оптимизированная версия)

🎯 Цель проекта

Адаптация десктопного приложения 1Code для полноценной работы на Windows с улучшенным пользовательским опытом и исправлением платформо-специфичных проблем.

✨ Основные фичи и улучшения

1. 🪟 Настройка стиля окна (Window Frame Preference)

Название: useNativeFrameAtom / Windows Window Frame Preference

Что это:

  • Пользователь может выбрать между нативным окном Windows (белая полоса заголовка) и кастомным темным окном без рамки
  • Настройка сохраняется и применяется после перезапуска

Зачем нужно:

  • Нативное окно: Интеграция с системой Windows, доступ к меню через Alt, стандартный вид
  • Кастомное окно: Темная тема, современный дизайн, больше места для контента

Где находится:

  • Настройки → Preferences → "Native Window Frame" (только на Windows)

Технические детали:

  • Атом Jotai для хранения предпочтения
  • IPC-обработчик для сохранения в main process
  • Автоматическое применение при запуске приложения

2. 🔔 Десктопные уведомления Windows

Название: Desktop Notifications / Windows Desktop Notifications

Что это:

  • Нативные уведомления Windows, которые появляются в системном трее
  • Показываются, когда агент завершает работу, а пользователь не смотрит на чат

Зачем нужно:

  • Уведомление о завершении задач агента, даже если приложение свернуто
  • Интеграция с системой уведомлений Windows
  • Улучшенный UX для многозадачности

Где находится:

  • Настройки → Preferences → "Desktop Notifications" (только на Windows)

Технические детали:

  • Использует Electron API Notification
  • Проверка видимости окна перед показом
  • Настраивается отдельно от звуковых уведомлений

3. 🎨 Темная полоса заголовка (Dark Title Bar)

Название: Windows Dark Title Bar / Custom Frameless Window

Что это:

  • Кастомная темная полоса заголовка вместо стандартной белой Windows
  • Полностью интегрирована с темой приложения (светлая/темная)

Зачем нужно:

  • Визуальная согласованность с темой приложения
  • Современный внешний вид
  • Больше контроля над UI

Технические детали:

  • Frameless window (frame: false)
  • Кастомный React-компонент WindowsTitleBar
  • Кнопки управления окном (свернуть, развернуть, закрыть)
  • Поддержка перетаскивания окна

4. 🛠️ Исправление разрешения путей (CWD Resolution Fix)

Название: CWD Path Resolution / Worktree Path Handling

Что это:

  • Правильное разрешение относительных путей в абсолютные на Windows
  • Исправление проблем с путями worktree (временные рабочие директории Git)

Зачем нужно:

  • Проблема: На Windows относительные пути типа ~/.21st/worktrees/... не работали
  • Решение: Автоматическое преобразование в абсолютные пути через os.homedir()
  • Результат: Стабильная работа с Git worktrees на Windows

Технические детали:

  • Валидация CWD перед запуском Claude
  • Fallback на путь проекта, если worktree недоступен
  • Поддержка как абсолютных, так и относительных путей

5. 📦 Поддержка Windows-бинарника Claude

Название: Windows Binary Support / Claude.exe Download

Что это:

  • Автоматическая загрузка правильной версии claude.exe для Windows
  • Исправление URL для загрузки (использует claude.exe вместо claude)

Зачем нужно:

  • Проблема: Оригинальный код загружал macOS/Linux версию
  • Решение: Определение платформы и загрузка Windows-версии
  • Версия: Claude Code 2.1.8+ с поддержкой Windows

Технические детали:

  • Скрипт download-claude-binary.mjs с проверкой платформы
  • Правильный URL: claude.exe вместо claude
  • Интеграция в GitHub Actions для автоматической сборки

6. 🧠 Отслеживание лимитов токенов моделей

Название: Model Max Output Tokens Tracking / Dynamic Token Limits

Что это:

  • Автоматическое определение максимального количества выходных токенов для разных моделей
  • Динамическая настройка Extended Thinking в зависимости от модели

Зачем нужно:

  • Проблема: Разные модели имеют разные лимиты токенов (например, Opus 4.5 = 64K, другие = 128K)
  • Решение: Обучение лимитов из ошибок SDK и применение при настройке Extended Thinking
  • Результат: Предотвращение ошибок "max_tokens exceeds limit"

Технические детали:

  • Атом modelMaxOutputTokensAtom для хранения лимитов
  • Парсинг ошибок SDK для извлечения лимитов
  • Автоматическая настройка maxThinkingTokens с учетом лимита модели

7. 🔄 Fallback на путь проекта

Название: Project Path Fallback / Worktree Recovery

Что это:

  • Если worktree недоступен или удален, используется путь основного проекта
  • Восстановление работоспособности без пересоздания worktree

Зачем нужно:

  • Проблема: Worktree может быть удален, но чат все еще ссылается на него
  • Решение: Автоматический fallback на путь проекта из базы данных
  • Результат: Приложение продолжает работать даже при проблемах с worktree

Технические детали:

  • Проверка существования worktree перед использованием
  • Запрос пути проекта из базы данных при ошибке
  • Валидация доступности пути перед использованием

8. 🏗️ Улучшения сборки для Windows

Название: Windows Build Improvements / Packaging Scripts

Что это:

  • Специализированные скрипты для сборки Windows-версии
  • Исправление проблем с better-sqlite3 native bindings
  • Подавление ложных ошибок winCodeSign

Зачем нужно:

  • Стабильная сборка на Windows
  • Правильная упаковка native модулей
  • Чистый вывод без ложных ошибок

Технические детали:

  • Скрипт package-windows.mjs с фильтрацией ошибок
  • Автоматическое копирование better-sqlite3 build директории
  • GitHub Actions workflow для автоматической сборки

📊 Сравнительная таблица

Фича Оригинал Наша версия Статус
Настройка стиля окна ❌ ✅ Добавлено
Десктопные уведомления ❌ ✅ Добавлено
Темная полоса заголовка ❌ ✅ Добавлено
CWD разрешение ⚠️ Частично ✅ Полностью Исправлено
Windows binary ⚠️ Не работает ✅ Работает Исправлено
Лимиты токенов ❌ ✅ Добавлено
Fallback на проект ❌ ✅ Добавлено
Сборка Windows ⚠️ Проблемы ✅ Стабильно Улучшено

🎨 Архитектура изменений

Frontend (Renderer)

  • Атомы Jotai: useNativeFrameAtom, desktopNotificationsEnabledAtom, modelMaxOutputTokensAtom
  • Компоненты: WindowsTitleBar, настройки в AgentsPreferencesTab
  • Хуки: use-desktop-notifications.ts для управления уведомлениями

Backend (Main Process)

  • IPC handlers: setWindowFramePreference, обработка уведомлений
  • CWD валидация: Проверка и разрешение путей в claude.ts
  • Worktree: Использование os.homedir() вместо process.env.HOME

Build System

  • Скрипты: package-windows.mjs, download-claude-binary.mjs
  • GitHub Actions: Автоматическая сборка Windows-версии
  • Фильтрация ошибок: Подавление ложных предупреждений

🚀 Результаты

Для пользователей:

  • ✅ Полноценная работа на Windows без проблем
  • ✅ Настраиваемый внешний вид (нативное/кастомное окно)
  • ✅ Уведомления о завершении работы агента
  • ✅ Стабильная работа с Git worktrees
  • ✅ Автоматическая настройка лимитов токенов

Для разработчиков:

  • ✅ Чистая архитектура с атомами Jotai
  • ✅ Легкое добавление новых Windows-фич
  • ✅ Совместимость с upstream (легкий merge)
  • ✅ Автоматическая сборка и тестирование

📝 Технический стек изменений

  • State Management: Jotai atoms для настроек
  • IPC: Electron IPC для связи main/renderer
  • UI: React компоненты для кастомного UI
  • Build: Electron Builder с кастомными скриптами
  • Git: Исправления работы с worktrees на Windows

🔮 Будущие улучшения

Потенциальные направления развития:

  • Поддержка Windows-специфичных шорткатов
  • Интеграция с Windows Search
  • Поддержка Windows 11 визуальных эффектов
  • Оптимизация производительности для Windows
  • Поддержка Windows Sandbox для изоляции

📚 Документация

Все изменения задокументированы в:

  • README.md - Общее описание Windows-поддержки
  • WINDOWS_DARK_TITLE_BAR_PATCH.md - Детали темной полосы заголовка
  • PATCH_SUMMARY.md - Сводка всех патчей
  • BUILD_WINDOWS.md - Инструкции по сборке

✅ Заключение

Все изменения направлены на:

  1. Улучшение UX - настройки, уведомления, внешний вид
  2. Исправление багов - пути, бинарники, worktrees
  3. Стабильность - сборка, обработка ошибок, fallback-механизмы

Форк остается совместимым с upstream и легко получает обновления, сохраняя все Windows-специфичные улучшения.