readme2demo — проверенные руководства и демо-видео из вашего README

_{▶ readme2demo создаёт собственное руководство: AI-агент запускает README этого репозитория в изолированной среде, свежий контейнер воспроизводит каждый шаг, затем демо-ролик рендерится. Полные результаты выполнения в examples/readme2demo · запуск на другом проекте в examples/toolhive.}

Генератор руководств и демо-видео с AI-верификацией. Укажите репозиторий. AI-агент читает README и фактически запускает его внутри защищённого Docker-песочницы. Только после успешного воспроизведения в чистой комнате он рендерит демо-видео (VHS) и публикует руководство, пошаговое руководство и документ по устранению неполадок.

Ценность не в том, что «AI пишет руководство», а в том, что руководство выполнялось дважды, прежде чем вы его увидели.

Посмотрите в действии: просмотрите проверенные примеры запусков — настоящие руководства, пошаговые инструкции и демо-видео, каждое независимо воспроизведённое в чистом контейнере перед публикацией.

Как это работает

URL репозитория → ingest/plan → запуск агента (в Docker) → нормализация транскрипта
        → выделение минимального пути → ПРОВЕРКА воспроизведения в свежем контейнере
        → создание tutorial.md + troubleshooting.md → рендеринг VHS видео

Полная архитектура описана в architecture/README.md.

Требования

Python ≥ 3.10, Docker
Аутентификация, один из вариантов:
- Ваша подписка Claude (без API-ключа): локальная установка Claude Code. Планировщик/дистиллятор/руководство выполняются по вашей подписке через --llm-backend claude-cli (claude -p), а агент в песочнице аутентифицируется с помощью CLAUDE_CODE_OAUTH_TOKEN (создайте его: claude setup-token). Полностью поддерживается для самостоятельных однопользовательских запусков на ваших собственных репозиториях — планы Pro/Max включают ежемесячный кредит Agent SDK, покрывающий claude -p.
- ANTHROPIC_API_KEY — поминутная оплата API; лучше всего для масштаба и параллелизма, и обязательно, если вы предоставляете readme2demo как сервис для других (согласно условиям Anthropic, аутентификация по подписке не может использоваться для многопользовательского продукта — см. ROADMAP.md). Добавьте --anthropic [model] для запуска агента в песочнице на движке OpenHands с моделью Claude вместо claude-code.
- Google Gemini (--gemini [model]): один GEMINI_API_KEY управляет всем сеансом без Claude — планировщик/дистиллятор/руководство используют Gemini, а агент в песочнице работает на движке OpenHands (также на Gemini). Ни одно имя модели не встроено (Google удаляет старые модели с ошибкой 404): укажите его при каждом запуске () или один раз экспортируйте . Установите дополнительный пакет: .

# запуск по вашей подписке Claude (без API-ключа) — поддерживается для самостоятельных запусков
claude setup-token        # интерактивно: подтвердите в браузере, затем СКОПИРУЙТЕ
                          # токен sk-ant-oat01-..., который он выводит (НЕ используйте $(...))
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
readme2demo run <repo-url> --llm-backend claude-cli

# запуск с поминутной оплатой API (масштаб, параллелизм или хостинг для других)
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url>              # --llm-backend auto автоматически выбирает api

# запуск всего сеанса на Google Gemini (агент OpenHands + проходы Gemini)
pip install 'readme2demo[gemini]'
docker build -t readme2demo/openhands:latest images/openhands   # однократно: образ песочницы OpenHands
export GEMINI_API_KEY=...
readme2demo run <repo-url> --gemini gemini-3.5-flash   # модель указана при запуске
export GEMINI_MODEL=gemini-3.5-flash                   # ...или установите один раз, затем:
readme2demo run <repo-url> --gemini                    # голый флаг читает GEMINI_MODEL

# запуск всего сеанса на OpenAI (агент OpenHands + проходы OpenAI)
pip install 'readme2demo[openai]'
export OPENAI_API_KEY=sk-...
readme2demo run <repo-url> --openai gpt-5.1            # или один раз экспортируйте OPENAI_MODEL

# запуск агента OpenHands с моделью Claude по API
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url> --anthropic                 # по умолчанию использует модель из конфига

Установка

pip install -e ".[dev]"
docker build -t readme2demo/base:latest images/base/
docker build -t readme2demo/openhands:latest images/openhands/   # только для --engine openhands / --gemini / --openai / --anthropic

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

readme2demo run https://github.com/example/tool
readme2demo run -gr https://github.com/example/tool             # то же самое через флаг
readme2demo run -s my_guide.md                                  # только руководство: без репозитория, ваше руководство самодостаточно
readme2demo run -gr https://github.com/example/tool -s my_guide.md   # оба: ваше руководство управляет всем
readme2demo run https://github.com/example/tool --gemini gemini-3.5-flash  # запуск на Google Gemini (требуется GEMINI_API_KEY; используется агент OpenHands; голый --gemini читает GEMINI_MODEL)
readme2demo run https://github.com/example/tool --openai gpt-5.1           # запуск на OpenAI (требуется OPENAI_API_KEY; используется агент OpenHands; голый --openai читает OPENAI_MODEL)
readme2demo run https://github.com/example/tool --anthropic                # агент OpenHands с моделью Claude по ANTHROPIC_API_KEY
readme2demo run https://github.com/example/tool --allow-docker-socket  # для инструментов, управляющих контейнерами (КОМПРОМИСС БЕЗОПАСНОСТИ: нарушает изоляцию песочницы — только доверенные репозитории)
readme2demo run https://github.com/example/tool --skip-video --budget-usd 3
readme2demo resume runs/tool-20260702-... --from-stage render
readme2demo report runs/tool-20260702-...

Репозиторий необязателен: передайте его позиционно или с помощью -gr/--github-repo, укажите руководство с -s/--step-by-step, или оба. Требуется хотя бы один. Только с руководством репозиторий не клонируется — руководство должно быть самодостаточным (установите опубликованный пакет или клонируйте необходимое как явный шаг); воспроизведение в свежем контейнере всё равно проверяет каждую команду.

Результаты сохраняются в runs/<run-id>/: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif, а также manifest.json с состояниями этапов и общей стоимостью.

GitHub Action — проверка README в CI

Получите красный крестик, когда ваш README перестаёт работать. Составное действие в корне репозитория устанавливает readme2demo из его собственного закреплённого чекаута, собирает образ песочницы, запускает полный конвейер для URL вашего репозитория и завершает проверку ошибкой, когда воспроизведение в свежем контейнере не проходит:

name: readme-check
on:
  push:
    branches: [main]        # режим url тестирует HEAD ветки по умолчанию — см. предупреждение ниже
    paths: ["README.md"]
  schedule:
    - cron: "0 6 * * 1"     # еженедельно: отслеживать изменения мира под неизменным README

permissions:
  contents: read

jobs:
  verify-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: alphacrack/readme2demo@main   # после релиза закрепите тег или SHA
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          skip-video: "true"

⚠ Только режим URL — это пока НЕ проверяет HEAD PR. Действие клонирует удалённый HEAD ветки по умолчанию repo-url (по умолчанию: репозиторий, запускающий рабочий процесс); приёмка принимает только URL https, --depth 1, без закрепления ref. На pull_request он бы тестировал README базовой ветки, а не PR — поэтому не подключайте его к PR, ожидая предварительной проверки. До #74 (приёмка локального пути) честными триггерами являются on: push на ветку по умолчанию и cron; вход repo-path для реальной проверки HEAD PR появится вместе с ним.

Стоимость: каждый запуск тратит реальные деньги агента на ваш ANTHROPIC_API_KEY — обычно несколько долларов, с жёстким лимитом budget-usd (по умолчанию "5"; запуск прерывается при превышении). Фильтр paths: плюс cron поддерживают расходы пропорциональными изменениям README, а skip-video: "true" сокращает реальное время (рендеринг не тратит деньги API в любом случае).

Проверка завершается ошибкой двумя различимыми способами, названными в логе шага: README сломан (конвейер завершён, воспроизведение в чистой комнате не удалось — обнаружено через readme2demo report --json, потому что readme2demo run намеренно завершается с кодом 0 для завершённого, но не проверенного запуска) и инфраструктура действия сломана (ненулевой выход конвейера: предварительная проверка, бюджет, Docker). Выходные данные: verified ("true"/"false") и run-dir; tutorial.md, step_by_step.md, verify.log (и demo.gif при включённом видео) загружаются как артефакт readme2demo-run.

step_by_step.md — источник видео

Демо-видео всегда строится из step_by_step.md: его шаги разбираются, и каждая безопасная для демо, обоснованная команда становится набранной командой в видео, а заголовок шага отображается как комментарий на экране. Три способа его появления, в порядке приоритета:

Вы передаёте свой: readme2demo run <url> -s my_guide.md — внедряется в клон как авторитетное руководство; планировщик и агент следуют ему, видео его воспроизводит. <url> здесь необязателен: readme2demo run -s my_guide.md запускается только с руководством в пустой песочнице.
Репозиторий содержит свой (step_by_step.md / step-by-step.md в корне или в docs/, любой регистр): та же обработка, автоматически.
Ничего нет: конвейер генерирует подробный step_by_step.md — каждая команда из проверенного commands.sh в виде пронумерованного шага с реальными захваченными выводами — затем строит видео из него. Готово для внесения обратно в репозиторий.

Шаги настройки (клонирование, установка, сборка) документируются в руководстве, но исключаются из видео — оно воспроизводится на проверенном, уже собранном рабочем дереве, показывая результат.

Каждое руководство содержит значок верификации: ✅ Verified on <date> · image <digest> · commit <sha> — или громкий ⚠ UNVERIFIED, если воспроизведение не прошло. Непроверенный вывод никогда не публикуется молча.

Конфигурация

Флаги CLI > readme2demo.toml > значения по умолчанию:

engine = "claude-code"      # или "openhands"
model = "claude-sonnet-5"   # планировщик/дистиллятор/руководство
max_turns = 60
budget_usd = 5.0
base_image = "readme2demo/base:latest"
skip_video = false

Разработка

python -m pytest tests/ -q            # 175 модульных тестов, не требуется docker/сеть
ruff check src/ tests/               # проверка корректности (соответствует CI)
python -m pytest -m integration      # требует docker + API-ключи (пока нет)

Модель безопасности

README-файлы — это ненадёжный код. Агент работает внутри жёсткого контейнера (cap-drop ALL, no-new-privileges, лимиты памяти/процессов/PID, не от root) — этот контейнер является границей разрешений. Известный компромисс MVP: API-ключ попадает в песочницу; используйте выделенный ключ с низким лимитом. Планируется прокси для исходящего трафика с внедрением ключа на стороне хоста (Milestone 4).

Полная модель угроз и сообщение о частных уязвимостях: SECURITY.md.

Проект и сообщество

Примеры — проверенные результаты, зафиксированные как доказательство
Дорожная карта — куда это движется (включая исследовательское направление хостинга/SaaS)
Участие — единственное необсуждаемое правило и как начать
Политика безопасности · Кодекс поведения
Архитектура — границы этапов и диаграммы

Лицензия MIT. CLI и конвейер верификации являются и останутся бесплатными и открытыми.

Участники

Огромное спасибо всем, кто внёс вклад в readme2demo!

readme2demo

Популярное