НейроКотΔ
НейроКотΔ
AI-powered tech digest
@neurokotd

Инструмент CLI для защиты структуры задач

Open source

Всем! Рассказывается история о том, как простая боль при работе с ИИ-ассистентами превратилась в 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 файл. После каждого изменения — копировали заново. Это работало... примерно неделю. Потом делали версии:
  • planv1.txt,
  • planv2.txt,
  • planv3final.txt,
  • planv3finalFINAL.txt.
Потом пробовали Notion, Obsidian, даже Excel. Но проблема оставалась: ИИ не знает, что можно менять, а что нельзя трогать.

Момент озарения

Однажды работали над большим проектом с автономным агентом. Агент должен был выполнять задачи по плану. И поняли, что нужно:
  • Стабильные идентификаторы — чтобы ссылка на задачу не ломалась при перемещении
  • Защита от изменений — чтобы утверждённые разделы нельзя было случайно изменить
  • История изменений — чтобы можно было откатиться
  • Простой интерфейс — чтобы и пользователи, и ИИ могли работать с этим
Так родился HBT — Hierarchical Block Text.

Что такое HBT

HBT — это CLI-инструмент для управления иерархическими задачами. Один Python-файл, никаких зависимостей, работает везде где есть Python 3.8+.

Ключевые идеи:

  • UUID вместо позиционных номеров
Каждый узел получает уникальный 12-символьный ID: 
└── a1b2c3d4 ⚪ Разработка API ✍️
    ├── b2c3d4e5 ⚪ Аутентификация ✍️
    └── c3d4e5f6 ⚪ База данных ✍️
Переместили «Аутентификацию» в другой раздел? ID остался b2c3d4e5. Все ссылки работают.
  • Статус locked/editable
Утвердили структуру раздела? Блокируем: 
hbt status --id b2c3d4e5 --mode locked
Теперь этот узел нельзя изменить или удалить. Даже случайно. Даже если очень хочется. 
└── b2c3d4e5 ⚪ Аутентификация 🔒  # Заблокировано!
  • Алиасы для удобства
Вместо b2c3d4e5 можно использовать человекочитаемое имя: 
hbt alias --id b2c3d4e5 --name auth
Теперь можно писать @auth вместо ID: 
hbt view --id @auth
hbt add --to @auth --text "JWT токены"
  • Автоматические снапшоты
Каждое изменение сохраняется. Накосячили? Откат в одну команду: 
hbt rollback --list                    # Посмотреть доступные точки
hbt rollback --restore auto20240218_100000.json  # Восстановить

Как это выглядит на практике

Создаётся структура проекта 
# Корневая задача
hbt add --text "Мой крутой проект" --alias project --locked

# Основные разделы
hbt add --to @project --text "Backend" --alias api
hbt add --to @project --text "Frontend" --alias fe
hbt add --to @project --text "DevOps" --alias devops

Детализация

hbt add --to @api --text "REST API"
hbt add --to @api --text "База данных"
hbt add --to @api --text "Авторизация" --alias auth

Смотрят что получилось

hbt view
└── a1b2c3d4 @project ⚪ Мой крутой проект 🔒
    ├── b2c3d4e5 @api ⚪ Backend ✍️
    │   ├── c3d4e5f6 ⚪ REST API ✍️
    │   ├── d4e5f6a7 ⚪ База данных ✍️
    │   └── e5f6a7b8 ⚪ Авторизация 🔒
    ├── f6a7b8c9 @fe ⚪ Frontend ✍️
    └── g7b8c9d0 @devops ⚪ DevOps ✍️

Скорректировали структуру:

hbt add --to @api --text "Серверное программирование"

hbt view
└── a1b2c3d4 @project ⚪ Мой крутой проект 🔒
    ├── b2c3d4e5 @api ⚪ Backend ✍️
    │   ├── c3d4e5f6 ⚪ REST API ✍️
    │   ├── d4e5f6a7 ⚪ База данных ✍️
    │   ├── e5f6a7b8 ⚪ Авторизация 🔒
    │   └── f6a7b8c9 ⚪ Серверное программирование ✍️
    ├── f6a7b8c9 @fe ⚪ Frontend ✍️
    └── g7b8c9d0 @devops ⚪ DevOps ✍️

Скорректировали статус:

hbt status --id e5f6a7b8 --mode editable

hbt view
└── a1b2c3d4 @project ⚪ Мой крутой проект 🔒
    ├── b2c3d4e5 @api ⚪ Backend ✍️
    │   ├── c3d4e5f6 ⚪ REST API ✍️
    │   ├── d4e5f6a7 ⚪ База данных ✍️
    │   ├── e5f6a7b8 ⚪ Авторизация ✍️
    │   └── f6a7b8c9 ⚪ Серверное программирование ✍️
    ├── f6a7b8c9 @fe ⚪ Frontend ✍️
    └── g7b8c9d0 @devops ⚪ DevOps ✍️

Скорректировали статус:

hbt status --id e5f6a7b8 --mode locked

hbt view
└── a1b2c3d4 @project ⚪ Мой крутой проект 🔒
    ├── b2c3d4e5 @api ⚪ Backend ✍️
    │   ├── c3d4e5f6 ⚪ REST API ✍️
    │   ├── d4e5f6a7 ⚪ База данных ✍️
    │   ├── e5f6a7b8 ⚪ Авторизация 🔒
    │   └── f6a7b8c9 ⚪ Серверное программирование ✍️
    ├── f6a7b8c9 @fe ⚪ Frontend ✍️
    └── g7b8c9d0 @devops ⚪ DevOps ✍
← Все статьи