HBT (Hierarchical Block Text) 🚀

HBT — production-grade CLI для управления иерархическими задачами с защитой от изменений. Идеальный инструмент для работы с LLM (ChatGPT, Claude), автономными агентами (OpenClaw) и сложными проектами.

Это как Git, но для структуры мыслей и задач.

💡 Проблема и Решение

😤 Знакомая боль?

Вы работаете с ChatGPT, Claude или автономным агентом OpenClaw над сложным проектом. Декомпозируете задачу на подзадачи, те — на ещё более мелкие. Через час у вас 50+ пунктов в красивой иерархии. И тут...

Проблема №1: ИИ "забывает" структуру

— Добавь подпункт к 3.2.1 — ИИ добавляет к 3.2, потому что контекст переполнен

Проблема №2: Случайные изменения утверждённого

— Перепиши раздел 4 — ИИ заодно "улучшает" разделы 3 и 5, которые вы уже согласовали с заказчиком

Проблема №3: Нет пути назад

— Верни как было 20 сообщений назад — ИИ галлюцинирует "как было", потому что не помнит

Проблема №4: Хрупкие ссылки

— Переместил пункт 2.3 в раздел 5 — Все ссылки "см. пункт 2.3" теперь битые

🎯 Как HBT решает эти проблемы

Проблема	Решение HBT
ИИ путает вложенность	UUID-адресация — каждый узел имеет уникальный ID, который не меняется при перемещении
Случайные изменения	Статус locked 🔒 — заблокированные узлы невозможно изменить или удалить
Нет истории	Автоматические снапшоты — каждое изменение сохраняется, откат в один клик
Битые ссылки	Алиасы — человекочитаемые имена (`@auth`, `@api`) вместо позиционных номеров
Потеря контекста	Экспорт — выгрузите актуальное дерево и скормите ИИ в новом чате
Агент теряет фокус	Команда next — автоматически находит следующую задачу для выполнения

🤖 Интеграция с OpenClaw

HBT идеально подходит для работы с автономными агентами:

# Агент получает следующую задачу
hbt next
# 🎯 Следующая задача: a1b2c3d4 — Реализовать JWT авторизацию [todo]

# Агент начинает работу
hbt set-progress --id a1b2c3d4 --state doing

# Агент завершает задачу
hbt set-progress --id a1b2c3d4 --state done

# Агент получает следующую задачу
hbt next

📁 Для OpenClaw доступен готовый файл скилла: openclaw_skill.md

🛡️ Гарантии безопасности

┌─────────────────────────────────────────────────────────┐
│  🔒 LOCKED = НЕПРИКОСНОВЕННО                            │
│                                                         │
│  • Нельзя изменить текст                               │
│  • Нельзя удалить                                      │
│  • Нельзя перезаписать детей (rewrite)                 │
│  • Даже если родитель editable — locked-дети защищены  │
└─────────────────────────────────────────────────────────┘

HBT — это ваш "source of truth" при работе с ИИ. Структура данных, которую нельзя случайно сломать.

🚀 Быстрый старт (5 минут)

После установки попробуйте базовые команды:

# 1. Создайте первую задачу
hbt add --text "Мой проект"

# 2. Посмотрите дерево
hbt view

# 3. Добавьте подзадачу (используйте ID из вывода)
hbt add --to abc123 --text "Первая подзадача"

# 4. Заблокируйте важный узел
hbt status --id abc123 --mode locked

# 5. Отметьте прогресс
hbt set-progress --id abc123 --state doing

Основные концепции:

Концепция	Описание	Пример
ID	12-символьный уникальный идентификатор	`a1b2c3d4e5f6`
Alias	Короткое имя для удобства	`@app`, `@auth`
Status	`locked` 🔒 или `editable` ✍️	Защита от изменений
Progress	`todo` ⚪ / `doing` 🔵 / `done` 🟢 / `blocked` 🔴	Статус выполнения
Tags	Метки для фильтрации	`#mvp`, `#backend`

⚙️ Установка

Требования

Python 3.8+
Поддерживаемые ОС: Linux, macOS, Windows (WSL)
Зависимости: только стандартная библиотека Python (zero dependencies!)

Вариант 1: Быстрый старт (без установки)

Просто скачайте файл и запускайте через Python:

# Скачайте hbt.py в папку вашего проекта
curl -O https://raw.githubusercontent.com/DanielLetto2020/hierarchical-block-text/master/hbt.py

# Запуск
python3 hbt.py --version
python3 hbt.py view
python3 hbt.py add --text "Моя первая задача"

Вариант 2: Установка как команда (Linux/macOS)

# Клонируйте репозиторий
git clone https://github.com/DanielLetto2020/hierarchical-block-text.git
cd hierarchical-block-text

# Сделайте исполняемым
chmod +x hbt.py

# Вариант A: Симлинк в /usr/local/bin (требует sudo)
sudo ln -s $(pwd)/hbt.py /usr/local/bin/hbt

# Вариант B: Симлинк в ~/.local/bin (без sudo)
mkdir -p ~/.local/bin
ln -s $(pwd)/hbt.py ~/.local/bin/hbt
# Убедитесь, что ~/.local/bin в PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Проверка
hbt --version

Вариант 3: Alias в shell

Добавьте в ваш ~/.bashrc или ~/.zshrc:

# Если hbt.py лежит в конкретной папке
alias hbt='python3 /path/to/hbt.py'

# Или если запускаете из папки проекта
alias hbt='python3 ./hbt.py'

Вариант 4: Windows

# PowerShell: создайте функцию в профиле
notepad $PROFILE

# Добавьте строку:
function hbt { python C:\path\to\hbt.py $args }

# Или используйте напрямую:
python hbt.py --version

Проверка установки

# Через команду hbt (если установили)
hbt --version
hbt view

# Через Python (всегда работает)
python3 hbt.py --version
python3 hbt.py view

💡 Совет: HBT создаёт файл tasks.json в текущей директории. Запускайте команды из корня вашего проекта.

🛠 Полный цикл разработки: Проект "Super App"

Пошаговый пример декомпозиции реального проекта с демонстрацией всех команд HBT.

📍 Шаг 1: Инициализация проекта

Создаём корневую задачу проекта. Сразу блокируем её и добавляем alias для удобства.

hbt add --text "Разработка Super App" --locked --alias app --tags core mvp

Вывод:

✅ Добавлено: a1b2c3d4e5f6 @app [L]

Состояние дерева (hbt view):

└── a1b2c3d4 @app ⚪ Разработка Super App #core #mvp 🔒

📄 tasks.json после этого шага

{
  "config": {
    "name": "New HBT Project",
    "version": "1.0.0",
    "auto_backup": true,
    "max_snapshots": 100,
    "default_status": "editable"
  },
  "schema_version": "1.0.0",
  "history": [
    {
      "timestamp": "2026-02-18 10:00:00",
      "action": "add",
      "node_id": "a1b2c3d4e5f6",
      "text": "Разработка Super App",
      "checksum": "abc123def456"
    }
  ],
  "tree": [
    {
      "id": "a1b2c3d4e5f6",
      "text": "Разработка Super App",
      "status": "locked",
      "progress": "todo",
      "visible": true,
      "tags": ["core", "mvp"],
      "alias": "app",
      "created_at": "2026-02-18T10:00:00",
      "updated_at": "2026-02-18T10:00:00",
      "parent_id": null,
      "children": []
    }
  ]
}

📍 Шаг 2: Декомпозиция первого уровня

Разбиваем проект на основные направления.

hbt add --to @app --text "Backend API" --alias api --tags backend
hbt add --to @app --text "Frontend (React Native)" --alias fe --tags frontend mobile
hbt add --to @app --text "DevOps & Infrastructure" --alias devops --tags infra

Вывод каждой команды:

✅ Добавлено: b2c3d4e5f6a7 @api [E]
✅ Добавлено: c3d4e5f6a7b8 @fe [E]
✅ Добавлено: d4e5f6a7b8c9 @devops [E]

Состояние дерева (hbt view):

└── a1b2c3d4 @app ⚪ Разработка Super App #core #mvp 🔒
    ├── b2c3d4e5 @api ⚪ Backend API #backend ✍️
    ├── c3d4e5f6 @fe ⚪ Frontend (React Native) #frontend #mobile ✍️
    └── d4e5f6a7 @devops ⚪ DevOps & Infrastructure #infra ✍️

📍 Шаг 3: Глубокая декомпозиция Backend

Детализируем Backend API.

hbt add --to @api --text "Аутентификация" --alias auth --tags auth security
hbt add --to @api --text "REST API endpoints" --alias rest --tags api
hbt add --to @api --text "База данных" --alias db --tags database

Состояние дерева (hbt view --id @api):

└── b2c3d4e5 @api ⚪ Backend API #backend ✍️
    ├── e5f6a7b8 @auth ⚪ Аутентификация #auth #security ✍️
    ├── f6a7b8c9 @rest ⚪ REST API endpoints #api ✍️
    └── a7b8c9d0 @db ⚪ База данных #database ✍️

📍 Шаг 4: Массовое добавление через rewrite

Быстро наполняем раздел аутентификации подпунктами.

hbt rewrite --id @auth "JWT токены" "OAuth 2.0 (Google, Apple)" "Refresh tokens" "Rate limiting"

Вывод:

✅ Подпункты e5f6a7b8 перезаписаны (4 шт.)

Состояние ветки (hbt view --id @auth):

└── e5f6a7b8 @auth ⚪ Аутентификация #auth #security ✍️
    ├── b8c9d0e1 ⚪ JWT токены ✍️
    ├── c9d0e1f2 ⚪ OAuth 2.0 (Google, Apple) ✍️
    ├── d0e1f2a3 ⚪ Refresh tokens ✍️
    └── e1f2a3b4 ⚪ Rate limiting ✍️

📄 Фрагмент tasks.json (узел @auth с детьми)

{
  "id": "e5f6a7b8c9d0",
  "text": "Аутентификация",
  "status": "editable",
  "progress": "todo",
  "visible": true,
  "tags": ["auth", "security"],
  "alias": "auth",
  "parent_id": "b2c3d4e5f6a7",
  "children": [
    {
      "id": "b8c9d0e1f2a3",
      "text": "JWT токены",
      "status": "editable",
      "progress": "todo",
      "visible": true,
      "tags": [],
      "alias": null,
      "parent_id": "e5f6a7b8c9d0",
      "children": []
    },
    {
      "id": "c9d0e1f2a3b4",
      "text": "OAuth 2.0 (Google, Apple)",
      "status": "editable",
      "progress": "todo",
      "visible": true,
      "tags": [],
      "alias": null,
      "parent_id": "e5f6a7b8c9d0",
      "children": []
    }
  ]
}

📍 Шаг 5: Работа с тегами

Добавляем теги для приоритизации и фильтрации.

# Добавить несколько тегов
hbt tag --id @auth --add priority-high sprint-1

# Удалить тег
hbt tag --id @auth --remove security

Вывод:

✅ Тег #priority-high добавлен к e5f6a7b8
✅ Тег #sprint-1 добавлен к e5f6a7b8
✅ Тег #security удален с e5f6a7b8

Фильтрация по тегам (hbt view --tags sprint-1):

└── e5f6a7b8 @auth ⚪ Аутентификация #auth #priority-high #sprint-1 ✍️
    ├── b8c9d0e1 ⚪ JWT токены ✍️
    ...

📍 Шаг 6: Установка alias для быстрого доступа

hbt alias --id b8c9d0e1 --name jwt

Вывод:

✅ Alias @jwt установлен для b8c9d0e1

Теперь можно обращаться к узлу как @jwt:

hbt view --id @jwt
hbt edit --id @jwt --text "JWT Access & Refresh токены"

📍 Шаг 7: Блокировка утверждённой структуры

После согласования архитектуры — блокируем.

# Заблокировать один узел
hbt status --id @auth --mode locked

# Заблокировать рекурсивно (узел + все дети)
hbt status --id @api --mode locked -r

Вывод:

✅ Статус e5f6a7b8 -> locked
✅ Статус b2c3d4e5 -> locked (рекурсивно)

Состояние дерева (hbt view --id @api):

└── b2c3d4e5 @api ⚪ Backend API #backend 🔒
    ├── e5f6a7b8 @auth ⚪ Аутентификация #auth #priority-high #sprint-1 🔒
    │   ├── b8c9d0e1 @jwt ⚪ JWT Access & Refresh токены 🔒
    │   ├── c9d0e1f2 ⚪ OAuth 2.0 (Google, Apple) 🔒
    │   ├── d0e1f2a3 ⚪ Refresh tokens 🔒
    │   └── e1f2a3b4 ⚪ Rate limiting 🔒
    ├── f6a7b8c9 @rest ⚪ REST API endpoints #api 🔒
    └── a7b8c9d0 @db ⚪ База данных #database 🔒

📍 Шаг 8: Защита в действии

Попытка изменить заблокированный узел:

hbt edit --id @jwt --text "Новый текст"

Вывод (ошибка):

🔒 Узел 'b8c9d0e1' заблокирован. Операция 'edit' запрещена

Попытка удалить узел с заблокированными детьми:

hbt delete --id @auth

Вывод (ошибка):

🔒 Узел 'e5f6a7b8' заблокирован. Операция 'delete' запрещена

Попытка перезаписать детей заблокированного узла:

hbt rewrite --id @auth "Новый пункт 1" "Новый пункт 2"

Вывод (ошибка):

🔒 Узел 'e5f6a7b8' заблокирован. Операция 'rewrite' запрещена

📍 Шаг 9: Отслеживание прогресса

Начинаем работу над задачами.

# Отметить начало работы
hbt set-progress --id @jwt --state doing

# Отметить выполнение
hbt set-progress --id @jwt --state done

# Заблокировать задачу (ждём внешний API)
hbt set-progress --id c9d0e1f2 --state blocked

Состояние (hbt view --id @auth):

└── e5f6a7b8 @auth ⚪ Аутентификация #auth #priority-high #sprint-1 🔒
    ├── b8c9d0e1 @jwt 🟢 JWT Access & Refresh токены 🔒
    ├── c9d0e1f2 🔴 OAuth 2.0 (Google, Apple) 🔒
    ├── d0e1f2a3 ⚪ Refresh tokens 🔒
    └── e1f2a3b4 ⚪ Rate limiting 🔒

Найти следующую задачу (hbt next):

🎯 Следующая задача: d0e1f2a3 — Refresh tokens [todo]

📍 Шаг 10: Фильтрованный просмотр

# Только задачи в работе
hbt view --progress doing

# Только заблокированные задачи
hbt view --progress blocked

# Только с тегом backend, глубина 2
hbt view --tags backend --depth 2

# Показать скрытые (удалённые) узлы
hbt view --all

📍 Шаг 11: Поиск и навигация

# Поиск по тексту
hbt search "OAuth"

Вывод:

c9d0e1f2 — OAuth 2.0 (Google, Apple)

# Поиск по тегам
hbt search "" --tags priority-high

Вывод:

e5f6a7b8 @auth — Аутентификация #auth #priority-high #sprint-1

# Показать путь до узла
hbt path --id @jwt

Вывод:

app: Разработка Super App → api: Backend API → auth: Аутентификация → jwt: JWT Access & Refresh токены

📍 Шаг 12: Перемещение узлов

Переносим задачу в другой раздел:

# Сначала разблокируем (если нужно)
hbt status --id e1f2a3b4 --mode editable

# Перемещаем Rate limiting в DevOps
hbt move --id e1f2a3b4 --to @devops

Вывод:

✅ Статус e1f2a3b4 -> editable
✅ Узел e1f2a3b4 перемещен в d4e5f6a7

📍 Шаг 13: Удаление (скрытие) узлов

hbt delete --id e1f2a3b4

Вывод:

✅ Узел e1f2a3b4 удален (скрыт)

Узел не удаляется физически, а скрывается (visible: false). Посмотреть скрытые:

hbt view --all

📍 Шаг 14: История изменений

hbt history --limit 10

Вывод:

[2026-02-18 10:00:00] abc123 ADD a1b2c3d4 — Разработка Super App
[2026-02-18 10:01:00] def456 ADD b2c3d4e5 — Backend API
[2026-02-18 10:02:00] 123abc ADD e5f6a7b8 — Аутентификация
[2026-02-18 10:03:00] 456def REWRITE e5f6a7b8 — Replaced with 4 items
[2026-02-18 10:04:00] 789abc STATUS_CHANGE b2c3d4e5 — locked (recursive=True)
[2026-02-18 10:05:00] abc789 PROGRESS b8c9d0e1 — done
[2026-02-18 10:06:00] def012 MOVE e1f2a3b4 — Moved to d4e5f6a7
[2026-02-18 10:07:00] 012def DELETE e1f2a3b4 — Rate limiting

📍 Шаг 15: Резервное копирование и откат

# Создать ручной снапшот
hbt backup

Вывод:

💾 Создан ручной снимок: manual_20260218_100500.json

# Посмотреть доступные снапшоты
hbt rollback --list

Вывод:

📜 Доступные точки восстановления:
  - auto_20260218_100000.json
  - auto_20260218_100100.json
  - auto_20260218_100200.json
  - manual_20260218_100500.json

# Восстановить из снапшота
hbt rollback --restore manual_20260218_100500.json

Вывод:

✅ База данных восстановлена из manual_20260218_100500.json

📍 Шаг 16: Статистика проекта

hbt stats

Вывод:

📊 Статистика проекта:
  Всего узлов: 12
  ├── Видимых: 11
  └── Скрытых: 1
  Заблокировано 🔒: 8
  Редактируемых ✍️: 4

  Прогресс:
    ⚪ todo: 8
    🔵 doing: 1
    🟢 done: 2
    🔴 blocked: 1

  Топ тегов:
    #backend: 4
    #auth: 2
    #security: 2
    #mvp: 1
    #core: 1

📍 Шаг 17: Экспорт для ИИ

hbt export ai_context.txt

Вывод:

📄 Экспортировано в ai_context.txt

Содержимое ai_context.txt:

└── a1b2c3d4 @app ⚪ Разработка Super App #core #mvp 🔒
    ├── b2c3d4e5 @api ⚪ Backend API #backend 🔒
    │   ├── e5f6a7b8 @auth ⚪ Аутентификация #auth #priority-high #sprint-1 🔒
    │   │   ├── b8c9d0e1 @jwt 🟢 JWT Access & Refresh токены 🔒
    │   │   ├── c9d0e1f2 🔴 OAuth 2.0 (Google, Apple) 🔒
    │   │   └── d0e1f2a3 ⚪ Refresh tokens 🔒
    │   ├── f6a7b8c9 @rest ⚪ REST API endpoints #api 🔒
    │   └── a7b8c9d0 @db ⚪ База данных #database 🔒
    ├── c3d4e5f6 @fe ⚪ Frontend (React Native) #frontend #mobile ✍️
    └── d4e5f6a7 @devops ⚪ DevOps & Infrastructure #infra ✍️

Теперь можно скопировать этот файл в новый чат с ИИ или передать автономному агенту как контекст проекта.

📍 Шаг 18: Импорт из файла

Создайте файл new_tasks.txt:

Настроить CI/CD
Kubernetes кластер
Мониторинг (Prometheus + Grafana)

hbt import --to @devops --file new_tasks.txt

Вывод:

✅ Импортировано 3 узлов

📍 Шаг 19: Проверка целостности

hbt verify

Вывод (если всё ок):

✅ Целостность данных в порядке

Вывод (если есть проблемы):

⚠️ Обнаружены проблемы:
  - Узел abc123 ссылается на несуществующего родителя def456
  - Дублирующийся alias 'api' у узлов abc123 и def456

📍 Шаг 20: Полная очистка (осторожно!)

hbt clear --yes

Вывод:

✅ База данных очищена. Снимок сохранен в .hbt_history

📋 Справочник команд

📁 Основные операции с узлами

Команда	Описание	Пример
`add`	Добавить новый узел	`hbt add --text "Задача" --to @parent --locked --alias task --tags mvp`
`edit`	Редактировать текст	`hbt edit --id @task --text "Новый текст"`
`delete`	Удалить (скрыть) узел	`hbt delete --id @task` или `--force` для locked
`move`	Переместить узел	`hbt move --id @task --to @newparent` или `--to root`
`rewrite`	Перезаписать детей	`hbt rewrite --id @parent "Пункт 1" "Пункт 2" "Пункт 3"`

👁️ Просмотр и поиск

Команда	Описание	Пример
`view`	Просмотр дерева	`hbt view --id @api --depth 2 --tags backend --progress todo`
`search`	Поиск по тексту/тегам	`hbt search "OAuth" --tags auth --all`
`path`	Путь до узла	`hbt path --id @jwt`
`next`	Следующая задача	`hbt next`
`stats`	Статистика проекта	`hbt stats`

🔒 Статусы и прогресс

Команда	Описание	Пример
`status`	Изменить locked/editable	`hbt status --id @api --mode locked -r` (рекурсивно)
`set-progress`	Изменить прогресс	`hbt set-progress --id @task --state done`

Значения progress: todo ⚪ → doing 🔵 → done 🟢 | blocked 🔴

🏷️ Теги и алиасы

Команда	Описание	Пример
`tag`	Добавить/удалить теги	`hbt tag --id @task --add urgent mvp --remove old`
`alias`	Установить короткое имя	`hbt alias --id a1b2c3d4 --name api`

💾 Версионирование

Команда	Описание	Пример
`backup`	Создать снапшот	`hbt backup`
`rollback`	Список/восстановление	`hbt rollback --list` или `--restore filename.json`
`history`	История изменений	`hbt history --limit 20`

📤 Импорт/Экспорт

Команда	Описание	Пример
`import`	Импорт из файла	`hbt import --to @devops --file tasks.txt`
`export`	Экспорт в текст	`hbt export context.txt`

🔧 Утилиты

Команда	Описание	Пример
`verify`	Проверка целостности	`hbt verify`
`clear`	Очистка базы	`hbt clear --yes`

Флаги команды `view`

Флаг	Описание
`--id ID`	Фокус на конкретном узле
`--depth N`	Ограничить глубину вывода
`--tags tag1 tag2`	Фильтр по тегам
`--progress todo doing`	Фильтр по прогрессу
`--all`	Показать скрытые узлы
`--raw`	Без цветов (для экспорта)

🧩 Структура данных (tasks.json)

HBT хранит все данные в одном JSON-файле с чёткой структурой:

{
  "config": {
    "name": "My Project",
    "version": "1.0.0",
    "auto_backup": true,
    "max_snapshots": 100,
    "default_status": "editable"
  },
  "schema_version": "1.0.0",
  "history": [
    {
      "timestamp": "2026-02-18 10:00:00",
      "action": "add",
      "node_id": "a1b2c3d4e5f6",
      "text": "Описание действия",
      "checksum": "abc123def456"
    }
  ],
  "tree": [
    {
      "id": "a1b2c3d4e5f6",
      "text": "Текст задачи",
      "status": "locked",
      "progress": "todo",
      "visible": true,
      "tags": ["mvp", "backend"],
      "alias": "api",
      "created_at": "2026-02-18T10:00:00",
      "updated_at": "2026-02-18T10:00:00",
      "parent_id": null,
      "children": []
    }
  ]
}

Поля узла (Node)

Поле	Тип	Описание
`id`	string	Уникальный 12-символьный UUID
`text`	string	Текст задачи
`status`	enum	`locked` 🔒 или `editable` ✍️
`progress`	enum	`todo` / `doing` / `done` / `blocked`
`visible`	bool	`false` = удалён (скрыт)
`tags`	array	Список тегов для фильтрации
`alias`	string?	Короткое имя для быстрого доступа
`parent_id`	string?	ID родителя (`null` для корневых)
`children`	array	Вложенные узлы

Файловая структура проекта

my-project/
├── tasks.json           # Основная база данных
└── .hbt_history/        # Автоматические снапшоты
    ├── auto_20260218_100000.json
    ├── auto_20260218_100100.json
    └── manual_20260218_120000.json

🔐 Гарантии безопасности

HBT спроектирован с приоритетом на сохранность данных:

🔒 Защита locked-узлов

┌─────────────────────────────────────────────────────────────┐
│  LOCKED-узел защищён от:                                    │
│                                                             │
│  ✗ edit      — нельзя изменить текст                       │
│  ✗ delete    — нельзя удалить                              │
│  ✗ rewrite   — нельзя перезаписать детей                   │
│  ✗ move      — можно перемещать (ID не меняется)           │
│                                                             │
│  Даже если родитель editable — locked-дети защищены!       │
└─────────────────────────────────────────────────────────────┘

💾 Атомарные операции

Каждое сохранение происходит через временный файл с последующим атомарным переименованием:

# Псевдокод процесса сохранения
1. Записать данные во временный файл (.tmp)
2. Проверить целостность записи
3. Атомарно переименовать .tmp → tasks.json
4. Создать снапшот в .hbt_history/

Это гарантирует, что даже при сбое питания файл не будет повреждён.

📜 История с контрольными суммами

Каждая запись в истории содержит SHA-256 чексумму:

{
  "timestamp": "2026-02-18 10:00:00",
  "action": "edit",
  "node_id": "a1b2c3d4e5f6",
  "text": "Старый текст -> Новый текст",
  "checksum": "abc123def456"
}

🔄 Автоматические снапшоты

Каждое изменение создаёт снапшот в .hbt_history/
По умолчанию хранится 100 последних снапшотов
Ручные снапшоты (hbt backup) не удаляются автоматически
Восстановление в один клик: hbt rollback --restore filename.json

✅ Проверка целостности

Команда hbt verify проверяет:

Все parent_id указывают на существующие узлы
Нет дублирующихся alias
Нет циклических ссылок в дереве

🧪 Тестирование

HBT включает полный набор тестов для проверки работоспособности всех функций.

Запуск тестов

# Простой запуск
python3 test_hbt.py

# Или через pytest (если установлен)
python3 -m pytest test_hbt.py -v

# Запуск конкретного теста
python3 -m pytest test_hbt.py::TestAddNode -v

Пример вывода

======================================================================
HBT (Hierarchical Block Text) — Тестирование
Версия: 1.0.0
======================================================================

test_node_creation (test_hbt.TestNodeModel) ... ok
test_node_is_locked (test_hbt.TestNodeModel) ... ok
test_add_root_node (test_hbt.TestAddNode) ... ok
test_add_child_node (test_hbt.TestAddNode) ... ok
...

======================================================================
ИТОГОВЫЙ ОТЧЁТ
======================================================================
Всего тестов: 62
✅ Успешно: 62
❌ Провалено: 0
💥 Ошибок: 0

🎉 ВСЕ ТЕСТЫ ПРОЙДЕНЫ УСПЕШНО!
   Код работает корректно и готов к использованию.
======================================================================

Что тестируется

Категория	Тесты
Модель Node	Создание, сериализация, проверка блокировки
Добавление узлов	Корневые, дочерние, с alias, с тегами, locked
Редактирование	Изменение текста, защита locked
Удаление	Скрытие, force-удаление, защита детей
Статусы	locked/editable, рекурсивное применение
Прогресс	todo/doing/done/blocked
Перезапись	rewrite детей, защита locked
Перемещение	move между родителями, в корень
Теги и алиасы	Добавление, удаление, уникальность
Поиск	По тексту, по тегам, скрытые узлы
Навигация	path, next
Статистика	Подсчёт узлов, тегов, прогресса
Бэкапы	Создание, восстановление снапшотов
Импорт/Экспорт	Файловые операции
Целостность	Проверка данных
Персистентность	Сохранение между сессиями

📄 Лицензия

CC BY 4.0 (Creative Commons Attribution 4.0 International)

Вы можете свободно использовать, изменять и распространять HBT в любых целях, включая коммерческие, при условии указания авторства.

См. файл LICENSE для деталей.

🤖 Интеграция с автономными агентами

OpenClaw

HBT включает готовый файл скилла для OpenClaw — openclaw_skill.md. Агент автоматически научится:

Просматривать структуру проекта (hbt view)
Получать следующую задачу (hbt next)
Отмечать прогресс выполнения
Добавлять новые подзадачи при декомпозиции
Блокировать завершённые разделы

Пример workflow агента

1. hbt view                           # Понять структуру проекта
2. hbt next                           # Получить задачу
3. ... выполнение задачи ...
4. hbt set-progress --id X --state done
5. hbt add --to X --text "Подзадача"  # Если нужна декомпозиция
6. goto 2

Aider

Aider — мощный AI-ассистент для программирования. HBT идеально дополняет его, предоставляя структурированный план работы.

Зачем HBT + Aider?

Проблема Aider	Решение с HBT
Aider не знает общую картину проекта	`hbt view` даёт полный контекст
Сложно отслеживать что уже сделано	`hbt set-progress` фиксирует прогресс
Нет защиты от переписывания готового	`locked` статус защищает код
Теряется фокус на больших проектах	`hbt next` указывает следующую задачу

Установка и настройка

# 1. Установите Aider (если ещё нет)
pip install aider-chat

# 2. Убедитесь, что hbt доступен
hbt --version

# 3. Создайте структуру проекта
hbt add --text "Мой проект" --alias project --locked
hbt add --to @project --text "Backend API" --alias api
hbt add --to @project --text "Frontend" --alias fe

Способ 1: Передача контекста через /run

Aider поддерживает выполнение shell-команд через /run. Используйте это для получения актуального состояния:

# В сессии Aider:
/run hbt view --raw

# Aider увидит:
└── a1b2c3d4 @project ⚪ Мой проект #core 🔒
    ├── b2c3d4e5 @api ⚪ Backend API ✍️
    └── c3d4e5f6 @fe ⚪ Frontend ✍️

Способ 2: Экспорт в файл контекста

Создайте файл с планом и добавьте его в Aider:

# Экспортируйте план
hbt export PROJECT_PLAN.md

# Запустите Aider с этим файлом
aider --read PROJECT_PLAN.md src/*.py

Теперь Aider видит структуру проекта и может ссылаться на неё.

Способ 3: Интеграция через .aider.conf.yml

Создайте конфигурацию для автоматической загрузки плана:

# .aider.conf.yml
read:
  - PROJECT_PLAN.md
  - hbt_context.txt

# Автоматически обновлять контекст перед сессией
# (добавьте в свой shell profile или Makefile)

# Makefile
aider-start:
	hbt export hbt_context.txt
	aider --read hbt_context.txt

Рабочий процесс HBT + Aider

Шаг 1: Планирование (HBT)

# Создаём структуру задач
hbt add --text "Реализовать REST API" --alias api --to @project
hbt rewrite --id @api "GET /users" "POST /users" "PUT /users/:id" "DELETE /users/:id"
hbt view

Шаг 2: Получение задачи

hbt next
# 🎯 Следующая задача: d4e5f6a7 — GET /users [todo]

Шаг 3: Работа в Aider

# Отмечаем начало работы
hbt set-progress --id d4e5f6a7 --state doing

# Запускаем Aider
aider src/api/users.py

# В Aider:
> Реализуй GET /users endpoint согласно плану:
> /run hbt view --id @api --raw

Шаг 4: Фиксация результата

# После завершения работы в Aider
hbt set-progress --id d4e5f6a7 --state done

# Блокируем готовый функционал
hbt status --id d4e5f6a7 --mode locked

# Переходим к следующей задаче
hbt next

Пример сессии

$ hbt next
🎯 Следующая задача: e5f6a7b8 — POST /users [todo]

$ hbt set-progress --id e5f6a7b8 --state doing
✅ Прогресс e5f6a7b8 -> doing

$ aider src/api/users.py
───────────────────────────────────────────────────
Aider v0.50.0
Model: claude-3-5-sonnet with diff edit format
───────────────────────────────────────────────────

> Реализуй POST /users endpoint для создания пользователя.
> Валидация: email (обязательный, уникальный), name (обязательный).
> Возвращай 201 Created с созданным пользователем.

# ... Aider генерирует код ...

> /run hbt set-progress --id e5f6a7b8 --state done
✅ Прогресс e5f6a7b8 -> done

> /run hbt next
🎯 Следующая задача: f6a7b8c9 — PUT /users/:id [todo]

Продвинутые сценарии

Декомпозиция в процессе работы:

# Aider понял, что задача сложнее — декомпозируем
> /run hbt add --to e5f6a7b8 --text "Валидация email"
> /run hbt add --to e5f6a7b8 --text "Хеширование пароля"
> /run hbt add --to e5f6a7b8 --text "Сохранение в БД"

Просмотр пути для контекста:

> /run hbt path --id @api
project: Мой проект → api: Backend API

Фильтрация по тегам:

# Показать только задачи текущего спринта
> /run hbt view --tags sprint-1 --progress todo

Профит от интеграции

✅ Структурированная работа — не теряетесь в большом проекте
✅ Защита готового кода — locked-задачи = стабильный код
✅ Прозрачный прогресс — всегда видно что сделано, что осталось
✅ Контекст для ИИ — Aider понимает общую картину
✅ История решений — можно откатиться к любому состоянию

Cursor

Cursor — AI-first IDE на базе VS Code. HBT интегрируется через терминал и файлы контекста.

Настройка

Создайте файл .cursorrules в корне проекта:

# HBT Integration
При работе над задачами используй HBT для управления прогрессом:
- Перед началом работы: выполни `hbt next` чтобы узнать текущую задачу
- После завершения: выполни `hbt set-progress --id <ID> --state done`
- Для контекста проекта: смотри файл PROJECT_PLAN.md

Структура проекта находится в tasks.json, не редактируй его напрямую.

Экспортируйте план для Cursor:

hbt export PROJECT_PLAN.md

В Cursor используйте Composer (Ctrl+I) с контекстом:

@PROJECT_PLAN.md Реализуй следующую задачу из плана

Workflow в Cursor

# Терминал Cursor
$ hbt next
🎯 Следующая задача: a1b2c3d4 — Реализовать авторизацию [todo]

$ hbt set-progress --id a1b2c3d4 --state doing

# ... работаете в Cursor с AI ...

$ hbt set-progress --id a1b2c3d4 --state done
$ hbt next

Cline (Claude Dev)

Cline — мощное VS Code расширение для работы с Claude. Поддерживает выполнение команд.

Настройка

Добавьте в системный промпт Cline:

Для управления задачами проекта используй CLI-инструмент HBT:
- `hbt view` — посмотреть структуру задач
- `hbt next` — получить следующую задачу
- `hbt set-progress --id <ID> --state doing|done` — отметить прогресс
- `hbt add --to <PARENT_ID> --text "текст"` — добавить подзадачу

Всегда начинай работу с `hbt next` и отмечай прогресс после завершения.

Пример диалога

User: Продолжи работу над проектом

Cline: Сначала посмотрю текущие задачи...
> hbt next
🎯 Следующая задача: b2c3d4e5 — Настроить базу данных [todo]

Отмечаю начало работы...
> hbt set-progress --id b2c3d4e5 --state doing

Теперь реализую настройку базы данных...

Continue

Continue — open-source AI-ассистент для VS Code и JetBrains.

Настройка config.json

{
  "customCommands": [
    {
      "name": "hbt-next",
      "description": "Получить следующую задачу HBT",
      "prompt": "Выполни команду `hbt next` и начни работу над указанной задачей"
    },
    {
      "name": "hbt-done", 
      "description": "Отметить задачу выполненной",
      "prompt": "Выполни `hbt set-progress --id {ID} --state done` для текущей задачи"
    }
  ],
  "contextProviders": [
    {
      "name": "file",
      "params": {
        "path": "PROJECT_PLAN.md"
      }
    }
  ]
}

Windsurf (Codeium)

Windsurf — AI IDE от Codeium с агентом Cascade.

Интеграция

Windsurf поддерживает выполнение терминальных команд. Добавьте в контекст:

# Перед сессией
hbt export WINDSURF_CONTEXT.md

В чате Cascade:

@WINDSURF_CONTEXT.md 
Это структура задач проекта. Используй `hbt next` для получения задачи
и `hbt set-progress` для отметки прогресса.

GitHub Copilot Workspace

Copilot Workspace — планирование и выполнение задач от GitHub.

Интеграция

Экспортируйте задачи в GitHub Issue:

hbt export .github/TASKS.md

Ссылайтесь на план в Issue:

## Задача
Реализовать функционал X

## План (HBT)
См. [TASKS.md](./TASKS.md) — узел @feature-x

Codex CLI (OpenAI)

Codex CLI — терминальный агент от OpenAI.

Использование

# Запуск с контекстом HBT
codex --context "$(hbt view --raw)" "Реализуй следующую задачу"

# Или через pipe
hbt next | codex "Выполни эту задачу"

Devin / SWE-agent

Для полностью автономных агентов создайте файл инструкций:

# agent_instructions.md
hbt export agent_instructions.md
echo "
## Инструкции для агента

1. Выполни \`hbt next\` для получения задачи
2. Отметь \`hbt set-progress --id <ID> --state doing\`
3. Выполни задачу
4. Отметь \`hbt set-progress --id <ID> --state done\`
5. Повтори с шага 1
" >> agent_instructions.md

Универсальная интеграция

HBT работает с любым инструментом, который умеет:

Выполнять shell-команды
Читать файлы

Инструмент	Метод интеграции
Cursor	`.cursorrules` + терминал
Cline	Системный промпт + команды
Continue	`config.json` + custom commands
Windsurf	Cascade + терминал
Copilot	Контекст через файлы
Codex CLI	Pipe / --context
Aider	`/run` команды
OpenClaw	`openclaw_skill.md`
AutoGPT	Custom tools
CrewAI	Tool wrapper
LangChain	Custom tool

Создание универсального контекста

# Скрипт для любого агента
#!/bin/bash
echo "=== HBT Project Context ===" > AI_CONTEXT.md
echo "" >> AI_CONTEXT.md
echo "## Текущая задача" >> AI_CONTEXT.md
hbt next >> AI_CONTEXT.md
echo "" >> AI_CONTEXT.md
echo "## Структура проекта" >> AI_CONTEXT.md
hbt view --raw >> AI_CONTEXT.md
echo "" >> AI_CONTEXT.md
echo "## Команды HBT" >> AI_CONTEXT.md
echo "- hbt next — следующая задача" >> AI_CONTEXT.md
echo "- hbt set-progress --id ID --state doing|done" >> AI_CONTEXT.md
echo "- hbt add --to ID --text 'текст'" >> AI_CONTEXT.md

👤 Автор

Максим Кузьминский (Maxim Kuzminsky)

📧 Email: i@m-letto.ru
🐙 GitHub: github.com/DanielLetto2020

HBT 1.0.0 — Декомпозируйте мега-задачи с хирургической точностью.

Made with ❤️ by Максим Кузьминский for AI-assisted development

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
hbt.py		hbt.py
openclaw_skill.md		openclaw_skill.md
tasks.json		tasks.json
test_hbt.py		test_hbt.py

Folders and files

Latest commit

History

Repository files navigation

HBT (Hierarchical Block Text) 🚀

💡 Проблема и Решение

😤 Знакомая боль?

🎯 Как HBT решает эти проблемы

🤖 Интеграция с OpenClaw

🛡️ Гарантии безопасности

🚀 Быстрый старт (5 минут)

⚙️ Установка

Требования

Вариант 1: Быстрый старт (без установки)

Вариант 2: Установка как команда (Linux/macOS)

Вариант 3: Alias в shell

Вариант 4: Windows

Проверка установки

🛠 Полный цикл разработки: Проект "Super App"

📍 Шаг 1: Инициализация проекта

📍 Шаг 2: Декомпозиция первого уровня

📍 Шаг 3: Глубокая декомпозиция Backend

📍 Шаг 4: Массовое добавление через rewrite

📍 Шаг 5: Работа с тегами

📍 Шаг 6: Установка alias для быстрого доступа

📍 Шаг 7: Блокировка утверждённой структуры

📍 Шаг 8: Защита в действии

📍 Шаг 9: Отслеживание прогресса

📍 Шаг 10: Фильтрованный просмотр

📍 Шаг 11: Поиск и навигация

📍 Шаг 12: Перемещение узлов

📍 Шаг 13: Удаление (скрытие) узлов

📍 Шаг 14: История изменений

📍 Шаг 15: Резервное копирование и откат

📍 Шаг 16: Статистика проекта

📍 Шаг 17: Экспорт для ИИ

📍 Шаг 18: Импорт из файла

📍 Шаг 19: Проверка целостности

📍 Шаг 20: Полная очистка (осторожно!)

📋 Справочник команд

📁 Основные операции с узлами

👁️ Просмотр и поиск

🔒 Статусы и прогресс

🏷️ Теги и алиасы

💾 Версионирование

📤 Импорт/Экспорт

🔧 Утилиты

Флаги команды view

🧩 Структура данных (tasks.json)

Поля узла (Node)

Файловая структура проекта

🔐 Гарантии безопасности

🔒 Защита locked-узлов

💾 Атомарные операции

📜 История с контрольными суммами

🔄 Автоматические снапшоты

✅ Проверка целостности

🧪 Тестирование

Запуск тестов

Пример вывода

Что тестируется

📄 Лицензия

🤖 Интеграция с автономными агентами

OpenClaw

Пример workflow агента

Aider

Зачем HBT + Aider?

Установка и настройка

Способ 1: Передача контекста через /run

Способ 2: Экспорт в файл контекста

Способ 3: Интеграция через .aider.conf.yml

Рабочий процесс HBT + Aider

Пример сессии

Продвинутые сценарии

Профит от интеграции

Cursor

Настройка

Workflow в Cursor

Cline (Claude Dev)

Настройка

Флаги команды `view`

Packages