Добавление аннотаций к плану: Освоение четырёх типов аннотаций

Чему вы научитесь

• ✅ Выделять текст плана и добавлять четыре различных типа аннотаций (удаление, замена, вставка, комментарий)
• ✅ Использовать быстрый ввод type-to-comment для прямого ввода комментариев
• ✅ Прикреплять изображения к аннотациям (справочные изображения, скриншоты и т.д.)
• ✅ Понимать значение и сценарии использования каждого типа аннотаций
• ✅ Просматривать экспортированный формат аннотаций в Markdown

Ваши текущие проблемы

Проблема 1: Знаете, что нужно удалить определённый фрагмент, но после выделения текста не знаете, какую кнопку нажать.

Проблема 2: Хотите заменить фрагмент кода, но на панели инструментов есть только "Удалить" и "Комментарий", нет опции "Заменить".

Проблема 3: Хотите сразу ввести комментарий к выделенному многострочному тексту, но каждый раз приходится сначала нажимать кнопку "Comment" — это неэффективно.

Проблема 4: Хотите прикрепить справочное изображение к фрагменту кода, но не знаете, как загрузить изображение.

Plannotator поможет вам:

• Чёткие иконки кнопок, сразу видно различие между удалением, заменой, вставкой и комментарием
• Быстрый ввод type-to-comment, прямой ввод без нажатия кнопок
• Поддержка прикрепления изображений в аннотациях для удобного добавления справочных изображений
• Автоматическое преобразование аннотаций в структурированный Markdown, который ИИ точно понимает

Когда использовать этот метод

Подходящие сценарии:

• Обзор плана реализации, созданного ИИ, требуется точная обратная связь по изменениям
• Определённый фрагмент не нужен (удаление)
• Определённый фрагмент нужно изменить на другой вариант (замена)
• После определённого фрагмента нужно добавить пояснение (вставка)
• Есть вопросы или предложения по определённому фрагменту (комментарий)

Неподходящие сценарии:

• Просто общее одобрение или отклонение плана (не нужны аннотации, достаточно прямого решения)
• Уже проверяете изменения кода (используйте функцию обзора кода)

🎒 Подготовка перед началом

Предварительные требования:

• ✅ Завершили обучение по основам обзора планов
• ✅ Знаете, как открыть интерфейс обзора планов Plannotator

Предположения этого урока:

• Вы уже открыли страницу обзора планов Plannotator
• На странице отображается план в формате Markdown, созданный ИИ

Основная концепция

Подробное описание типов аннотаций

Plannotator поддерживает четыре типа аннотаций плана (плюс один тип глобального комментария):

Тип аннотации	Иконка	Назначение	Требуется ввод содержимого
Удаление (DELETION)	🗑️	Отметить, что этот фрагмент должен быть удалён из плана	❌ Не требуется
Комментарий (COMMENT)	💬	Задать вопрос или предложение по выделенному фрагменту	✅ Требуется ввод комментария
Замена (REPLACEMENT)	Реализуется через комментарий	Заменить выделенный фрагмент новым содержимым	✅ Требуется ввод нового содержимого
Вставка (INSERTION)	Реализуется через комментарий	Вставить новое содержимое после выделенного фрагмента	✅ Требуется ввод нового содержимого
Глобальный комментарий (GLOBAL_COMMENT)	Поле ввода внизу страницы	Дать обратную связь по всему плану	✅ Требуется ввод комментария

Почему у замены и вставки нет отдельных кнопок?

Потому что, согласно реализации в исходном коде, замена и вставка по сути являются специальными типами комментариев (packages/ui/utils/parser.ts:287-296):

• Замена: содержимое комментария используется как новый текст для замены
• Вставка: содержимое комментария используется как новый текст для вставки

Они оба создаются с помощью кнопки Комментарий (COMMENT), различие заключается в том, как вы описываете своё намерение.

Рабочий процесс панели инструментов

Выделить текст → Появляется панель инструментов (шаг меню)
                  │
                  ├── Нажать Delete → Немедленно создаётся аннотация удаления
                  ├── Нажать Comment → Переход к шагу ввода → Ввод содержимого → Сохранить
                  └── Прямой ввод символа → type-to-comment → Автоматический переход к шагу ввода

Различие между двумя шагами:

• Шаг меню: выбор типа операции (удаление, комментарий, отмена)
• Шаг ввода: ввод содержимого комментария или прикрепление изображения (из комментария/замены/вставки)

Быстрый ввод type-to-comment

Это ключевая функция для повышения эффективности. После выделения фрагмента текста сразу начинайте печатать (не нужно нажимать никакие кнопки), и панель инструментов автоматически:

1. Переключится в режим "комментарий"
2. Поместит первый введённый символ в поле ввода
3. Автоматически установит курсор в конец поля ввода

Расположение в исходном коде: packages/ui/components/AnnotationToolbar.tsx:127-147

Следуйте инструкциям

Шаг 1: Запуск обзора плана

Зачем Нужен реальный план для практики добавления аннотаций.

Действия

Запустите обзор плана в Claude Code или OpenCode:

# Пример Claude Code: после того как ИИ создаст план, он вызовет ExitPlanMode
"Пожалуйста, создайте план реализации функции аутентификации пользователей"

# Дождитесь завершения плана ИИ, Plannotator автоматически откроется в браузере

Что вы должны увидеть:

• Браузер открывает страницу обзора плана
• На странице отображается план реализации в формате Markdown

Шаг 2: Добавление аннотации удаления

Зачем Аннотация удаления используется для отметки содержимого, которое не должно появиться в финальном плане.

Действия

1. Найдите в плане абзац, который вам не нужен (например, описание несвязанной функции)
2. Выделите текст мышью
3. Панель инструментов автоматически появится, нажмите кнопку удаления (🗑️)

Что вы должны увидеть:

• Выделенный текст отображается в стиле удаления (обычно зачёркнутый или с красным фоном)
• Панель инструментов автоматически закрывается

Особенность аннотации удаления

Аннотация удаления не требует ввода содержимого. После нажатия кнопки удаления аннотация сразу создаётся.

Шаг 3: Использование type-to-comment для добавления комментария

Зачем Комментарий — самый часто используемый тип аннотации, type-to-comment позволяет сэкономить одно нажатие кнопки.

Действия

1. Выделите текст в плане (например, имя функции или описание)
2. Не нажимайте никакие кнопки, сразу начинайте печатать
3. Введите содержимое комментария (например: "Это имя функции недостаточно понятно")
4. Нажмите Enter для сохранения или нажмите кнопку Save

Что вы должны увидеть:

• Панель инструментов автоматически переключается в режим поля ввода
• Первый введённый символ уже находится в поле ввода
• Курсор автоматически установлен в конец поля ввода
• После нажатия Enter выделенный текст отображается в стиле комментария (обычно с жёлтым фоном)

Горячие клавиши type-to-comment

• Enter: сохранить аннотацию (если в поле ввода есть содержимое)
• Shift + Enter: перенос строки (используется при вводе многострочных комментариев)
• Escape: отменить ввод, вернуться к шагу меню

Шаг 4: Добавление аннотации замены

Зачем Аннотация замены используется для замены выделенного фрагмента новым содержимым, ИИ изменит план согласно вашей аннотации.

Действия

1. Выделите текст в плане (например, "Использовать JWT token для аутентификации")
2. Используйте type-to-comment или нажмите кнопку комментария
3. В поле ввода введите новое содержимое (например: "Использовать session cookie для аутентификации")
4. Нажмите Enter для сохранения

Что вы должны увидеть:

• Выделенный текст отображается в стиле комментария
• В боковой панели аннотаций отображается содержимое вашего комментария

Формат после экспорта (packages/ui/utils/parser.ts:292-296):

## 1. Change this

**From:**

Использовать JWT token для аутентификации

**To:**

Использовать session cookie для аутентификации

Различие между заменой и удалением

• Удаление: прямое удаление содержимого, не требуется объяснение причины
• Замена: замена старого содержимого новым, требуется указать новое содержимое

Шаг 5: Добавление аннотации вставки

Зачем Аннотация вставки используется для добавления пояснения или фрагмента кода после выделенного фрагмента.

Действия

1. Выделите текст в плане (например, конец сигнатуры функции)
2. Используйте type-to-comment или нажмите кнопку комментария
3. В поле ввода введите содержимое для вставки (например: ", необходимо обработать случай неудачной аутентификации")
4. Нажмите Enter для сохранения

Что вы должны увидеть:

• Выделенный текст отображается в стиле комментария
• В боковой панели аннотаций отображается ваш комментарий

Формат после экспорта (packages/ui/utils/parser.ts:287-290):

## 1. Add this

, необходимо обработать случай неудачной аутентификации

Шаг 6: Прикрепление изображения к аннотации

Зачем Иногда текстового описания недостаточно, нужно прикрепить справочное изображение или скриншот.

Действия

1. Выделите любой текст, перейдите к шагу ввода (нажмите кнопку комментария или используйте type-to-comment)
2. Рядом с полем ввода на панели инструментов нажмите кнопку прикрепления (📎)
3. Выберите изображение для загрузки (поддерживаются форматы PNG, JPEG, WebP)
4. Можете продолжить ввод содержимого комментария
5. Нажмите Enter для сохранения

Что вы должны увидеть:

• Миниатюра изображения отображается в поле ввода
• После сохранения изображение отображается в боковой панели аннотаций

Место хранения изображений

Загруженные изображения сохраняются в локальной директории /tmp/plannotator (расположение в коде: packages/server/index.ts:163). Если очистить временные файлы, изображения будут потеряны.

Шаг 7: Добавление глобального комментария

Зачем Когда у вас есть обратная связь по всему плану (не по конкретному фрагменту текста), используйте глобальный комментарий.

Действия

1. Найдите поле ввода внизу страницы (метка может быть "Add a general comment about the plan...")
2. Введите содержимое комментария
3. Нажмите Enter для сохранения или нажмите кнопку отправки

Что вы должны увидеть:

• Комментарий появляется в области глобальных комментариев внизу страницы
• Комментарий отображается как отдельная карточка, не связанная с каким-либо текстовым блоком

Глобальный комментарий vs текстовый комментарий

• Глобальный комментарий: обратная связь по всему плану, не связан с конкретным текстом (например, "Во всём плане отсутствует учёт производительности")
• Текстовый комментарий: обратная связь по определённому фрагменту текста, будет подсвечивать соответствующий текст

Контрольная точка ✅

После завершения вышеуказанных шагов вы должны:

• [ ] Успешно добавили как минимум одну аннотацию удаления
• [ ] Использовали type-to-comment для добавления комментария
• [ ] Добавили аннотации замены и вставки
• [ ] Прикрепили изображение к аннотации
• [ ] Добавили глобальный комментарий
• [ ] Видите список всех аннотаций в правой боковой панели

Предупреждения о подводных камнях

Подводный камень 1: Не могу найти кнопку "Заменить"

Неправильные действия:

• После выделения текста на панели инструментов есть только Delete и Comment, нет кнопок Replace или Insert

Правильный подход:

• Замена и вставка реализуются через кнопку Комментарий (COMMENT)
• В содержимом комментария опишите своё намерение (замена или вставка)
• ИИ поймёт ваше намерение на основе содержимого комментария

Подводный камень 2: type-to-comment не работает

Возможные причины:

1. Текст не выделен
2. Сначала нажали какую-то кнопку, панель инструментов уже перешла к шагу ввода
3. Ввели специальную клавишу (Ctrl, Alt, Escape и т.д.)

Правильный подход:

1. Сначала выделите текст, убедитесь, что панель инструментов отображается на шаге меню (есть кнопки Delete, Comment)
2. Прямо вводите обычные символы (буквы, цифры, знаки препинания)
3. Не нажимайте функциональные клавиши

Подводный камень 3: Не могу найти загруженное изображение

Возможные причины:

• Изображение сохранено в директории /tmp/plannotator
• Система очистила временные файлы

Правильный подход:

• Если нужно долгосрочное хранение изображений, рекомендуется скопировать их в директорию проекта
• При экспорте аннотаций путь к изображению абсолютный, убедитесь, что другие инструменты могут получить к нему доступ

Подводный камень 4: Нажал Enter для переноса строки, но аннотация сохранилась

Неправильные действия:

• В поле ввода хотел перенести строку, прямо нажал Enter, в результате аннотация сохранилась

Правильный подход:

• Используйте Shift + Enter для переноса строки
• Клавиша Enter предназначена исключительно для сохранения аннотации

Краткое содержание урока

Четыре типа аннотаций:

• Удаление (DELETION): отметить содержимое, которое не должно появиться в плане
• Замена (REPLACEMENT): заменить выделенный фрагмент новым содержимым (реализуется через комментарий)
• Вставка (INSERTION): добавить содержимое после выделенного фрагмента (реализуется через комментарий)
• Комментарий (COMMENT): задать вопрос или предложение по выделенному фрагменту
• Глобальный комментарий (GLOBAL_COMMENT): обратная связь по всему плану

Ключевые операции:

• Выделить → появляется панель инструментов → выбрать тип операции
• type-to-comment: прямой ввод символа, автоматический переход в режим комментария
• Shift + Enter: перенос строки; Enter: сохранить
• Кнопка прикрепления: загрузить изображение в аннотацию

Формат экспорта аннотаций:

• Удаление: ## Remove this + исходный текст
• Вставка: ## Add this + новый текст
• Замена: ## Change this + сравнение From/To
• Комментарий: ## Feedback on: "..." + содержимое комментария

Анонс следующего урока

В следующем уроке мы изучим Добавление разметки изображений.

Вы узнаете:

• Как прикреплять изображения в обзоре планов
• Использовать инструменты кисти, стрелки, круга для разметки
• Размеченные изображения как справочная обратная связь

---

Приложение: Справка по исходному коду

Нажмите, чтобы развернуть расположение в исходном коде

Время обновления: 2026-01-24

Функция	Путь к файлу	Строки
Определение перечисления типов аннотаций	packages/ui/types.ts	1-7
Интерфейс Annotation	packages/ui/types.ts	11-33
Компонент панели инструментов аннотаций	packages/ui/components/AnnotationToolbar.tsx	29-272
Форматирование экспорта аннотаций	packages/ui/utils/parser.ts	246-323
Парсинг Markdown в Blocks	packages/ui/utils/parser.ts	70-244
Компонент Viewer (обработка выделения текста)	packages/ui/components/Viewer.tsx	66-350

Ключевые константы:

• AnnotationType.DELETION = 'DELETION': тип аннотации удаления
• AnnotationType.INSERTION = 'INSERTION': тип аннотации вставки
• AnnotationType.REPLACEMENT = 'REPLACEMENT': тип аннотации замены
• AnnotationType.COMMENT = 'COMMENT': тип аннотации комментария
• AnnotationType.GLOBAL_COMMENT = 'GLOBAL_COMMENT': тип глобального комментария

Ключевые функции:

• exportDiff(blocks, annotations): экспорт аннотаций в формат Markdown, включая сравнение From/To
• parseMarkdownToBlocks(markdown): парсинг Markdown в линейный массив Block
• createAnnotationFromSource(): создание объекта Annotation из выделения текста