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): укажите его при каждом запуске (--gemini gemini-3.5-flash) или один раз экспортируйте GEMINI_MODEL. Установите дополнительный пакет: pip install 'readme2demo[gemini]'.
- OpenAI (--openai [model]): то же самое, что и Gemini — один OPENAI_API_KEY управляет проходами и агентом OpenHands, имя модели не встроено (--openai gpt-5.1 или экспорт OPENAI_MODEL). Установите дополнительный пакет: pip install 'readme2demo[openai]'.
Опционально: LLM_API_KEY + LLM_MODEL для --engine openhands (экспериментально) с любым другим провайдером litellm — предустановки выше заполняют их автоматически

# запуск по вашей подписке 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-...

readme2demo v0.7.5