Привет, Хабр! Меня зовут Максим, и я хочу рассказать историю о том, как простая боль при работе с ИИ-ассистентами превратилась в open-source проект, который, надеюсь, пригодится и вам.
Предыстория: когда всё началось
Последний год я активно использую локальные ИИ-агенты для работы над проектами. Не просто «напиши функцию», а полноценная декомпозиция задач: разбиваю большой проект на модули, модули на задачи, задачи на подзадачи. Через час работы у меня красивая иерархия из 50+ пунктов.
И вот тут начинается веселье.
Боль №1: «Добавь подпункт к 3.2.1»
Пишу в чат:
— Добавь подпункт к 3.2.1
А ИИ добавляет к 3.2. Или к 3.1. Или вообще создаёт новый раздел 4. Потому что контекст переполнен, и модель уже не помнит точную структуру.
Боль №2: «Перепиши раздел 4»
Прошу переписать один раздел, а ИИ заодно «улучшает» разделы 3 и 5. Которые я уже согласовал с заказчиком. Которые были идеальны.
Боль №3: «Верни как было»
— Верни структуру как было 20 сообщений назад
ИИ начинает галлюцинировать «как было», потому что не помнит. И приходилось вручную откатывать изменения, перечитывая историю чата и восстанавливая структуру по памяти.
Боль №4: Хрупкие ссылки
Переместил пункт 2.3 в раздел 5. Теперь он 5.4. А все ссылки «см. пункт 2.3» в других местах — битые. И ИИ про них не знает.
Первые попытки решения
Сначала я просто копировал структуру в отдельный.txtфайл. После каждого изменения — копировал заново. Это работало... примерно неделю.
Потом я начал делать версии:plan_v1.txt,plan_v2.txt,plan_v3_final.txt,plan_v3_final_FINAL.txt. Знакомо, да?
Потом я попробовал Notion, Obsidian, даже Excel. Но проблема оставалась:ИИ не знает, что можно менять, а что нельзя трогать.
Момент озарения
Однажды я работал над большим проектом с автономным агентом. Агент должен был выполнять задачи по плану. И я понял, что мне нужно:
- Стабильные идентификаторы— чтобы ссылка на задачу не ломалась при перемещении
- Защита от изменений— чтобы утверждённые разделы нельзя было случайно изменить
- История изменений— чтобы можно было откатиться
- Простой интерфейс— чтобы и я, и ИИ могли работать с этим
Так родился HBT — Hierarchical Block Text.
Что такое HBT
HBT — это CLI-инструмент для управления иерархическими задачами. Один Python-файл, никаких зависимостей, работает везде где есть Python 3.8+.
Ключевые идеи:
UUID вместо позиционных номеров
Каждый узел получает уникальный 12-символьный ID:
Переместил «Аутентификацию» в другой раздел? ID осталсяb2c3d4e5. Все ссылки работают.
Статус locked/editable
Утвердили структуру раздела? Блокируем:
Теперь этот узел нельзя изменить или удалить. Даже случайно. Даже если очень хочется.
Алиасы для удобства
Вместоb2c3d4e5можно использовать человекочитаемое имя:
Теперь можно писать@authвместо ID:
Автоматические снапшоты
Каждое изменение сохраняется. Накосячили? Откат в одну команду:
Как это выглядит на практике
Создаём структуру проекта
Смотрим что получилось
Быстро наполняем раздел
Одной командой создали 4 подпункта.
Блокируем утверждённое
Теперь весь Backend заблокирован. Никто (включая вас в 3 часа ночи) не сможет случайно его сломать.
Отслеживаем прогресс
Находим следующую задачу
Идеально для автономных агентов: получил задачу → выполнил → отметил done → получил следующую.
Интеграция с ИИ-инструментами
Экспорт контекста для ИИ
Экспортируем структуру и передаём агенту:
Теперь агент видит актуальную структуру и может ссылаться на узлы по ID или alias.
С автономными агентами
Агент выполняет простой цикл:
Что под капотом
- Один файлhbt.py— никаких зависимостей, только стандартная библиотека Python
- JSON-хранилищеtasks.json— человекочитаемый формат, можно редактировать руками
- Атомарные операции— запись через временный файл, данные не потеряются при сбое
- 62 теста— всё покрыто, можно доверять
Какие боли закрывает HBT
ИИ путает вложенность
UUID-адресация — ID не меняется при перемещении
Случайные изменения утверждённого
Статусlocked— заблокированное нельзя изменить
Нет истории
Автоматические снапшоты каждого изменения
Битые ссылки
Алиасы@authвместо позиционных номеров
Потеря контекста
Экспорт актуальной структуры для нового чата
Агент теряет фокус
Командаnext— автоматически находит следующую задачу
Почему я решил поделиться
Инструмент решает мою конкретную боль. Но я уверен, что не один такой. Если вы:
- Работаете с ИИ над сложными проектами
- Устали от того, что структура «плывёт»
- Хотите защитить утверждённые разделы от случайных изменений
- Используете автономных агентов и нужен чёткий план
...то HBT может вам пригодиться.
Проект полностью open-source под лицензией CC BY 4.0. Используйте, форкайте, улучшайте.
- GitHub:github.com/DanielLetto2020/hierarchical-block-text
- Документация: в README.md репозитория
Буду рад обратной связи в комментариях. Если есть идеи по улучшению — welcome в Issues на GitHub.
Спасибо за внимание! 🚀