alphacrack/readme2demoПроверенные руководства и демонстрационные видео из вашего README. ИИ-агент запускает их в защищенной Docker-песочнице и воспроизводит в новом контейнере перед публикацией.
# readme2demo — проверенные руководства и демо-видео из вашего README
[](https://github.com/alphacrack/readme2demo/actions/workflows/ci.yml)
[](https://github.com/alphacrack/readme2demo/blob/main/LICENSE)
[](https://github.com/alphacrack/readme2demo/blob/main/pyproject.toml)
<!-- HERO:START — scripts/self-demo.sh перезаписывает этот блок свежим результатом самозапуска.
Запустите локально (требуются Docker + VHS + учётные данные модели):
./scripts/self-demo.sh
Он запускает readme2demo на этом же репозитории, следуя docs/step-by-step.md,
и вставляет проверенное demo.gif прямо сюда. -->
[](https://github.com/alphacrack/readme2demo/tree/main/examples/readme2demo)
<sub>▶ readme2demo создаёт собственное руководство: AI-агент запускает README этого репозитория в изолированной среде, свежий контейнер воспроизводит каждый шаг, затем демо-ролик рендерится. Полные результаты выполнения в <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/readme2demo">examples/readme2demo</a> · запуск на другом проекте в <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/toolhive">examples/toolhive</a>.</sub>
<!-- HERO:END -->
**Генератор руководств и демо-видео с AI-верификацией.** Укажите репозиторий. AI-агент читает README и фактически запускает его внутри защищённого Docker-песочницы. Только после успешного воспроизведения в чистой комнате он рендерит демо-видео (VHS) и публикует руководство, пошаговое руководство и документ по устранению неполадок.
Ценность не в том, что «AI пишет руководство», а в том, что руководство **выполнялось дважды**, прежде чем вы его увидели.
**Посмотрите в действии:** просмотрите [проверенные примеры запусков](https://github.com/alphacrack/readme2demo/tree/main/examples) — настоящие руководства, пошаговые инструкции и демо-видео, каждое независимо воспроизведённое в чистом контейнере перед публикацией.
## Как это работает
```
URL репозитория → ingest/plan → запуск агента (в Docker) → нормализация транскрипта
→ выделение минимального пути → ПРОВЕРКА воспроизведения в свежем контейнере
→ создание tutorial.md + troubleshooting.md → рендеринг VHS видео
```
Полная архитектура описана в [architecture/README.md](https://github.com/alphacrack/readme2demo/blob/main/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](https://github.com/alphacrack/readme2demo/blob/main/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 — предустановки выше заполняют их автоматически
```bash
# запуск по вашей подписке 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 # по умолчанию использует модель из конфига
```
## Установка
```bash
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
```
## Использование
```bash
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 вашего репозитория и **завершает проверку ошибкой, когда воспроизведение в свежем контейнере не проходит**:
```yaml
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](https://github.com/alphacrack/readme2demo/issues/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`: его шаги разбираются, и каждая безопасная для демо, обоснованная команда становится набранной командой в видео, а заголовок шага отображается как комментарий на экране. Три способа его появления, в порядке приоритета:
1. **Вы передаёте свой**: `readme2demo run <url> -s my_guide.md` — внедряется в клон как авторитетное руководство; планировщик и агент следуют ему, видео его воспроизводит. `<url>` здесь необязателен: `readme2demo run -s my_guide.md` запускается только с руководством в пустой песочнице.
2. **Репозиторий содержит свой** (`step_by_step.md` / `step-by-step.md` в корне или в `docs/`, любой регистр): та же обработка, автоматически.
3. **Ничего нет**: конвейер *генерирует* подробный `step_by_step.md` — каждая команда из проверенного `commands.sh` в виде пронумерованного шага с реальными захваченными выводами — затем строит видео из него. Готово для внесения обратно в репозиторий.
Шаги настройки (клонирование, установка, сборка) документируются в руководстве, но исключаются из видео — оно воспроизводится на проверенном, уже собранном рабочем дереве, показывая результат.
Каждое руководство содержит значок верификации: `✅ Verified on <date> · image <digest> · commit <sha>` — или громкий `⚠ UNVERIFIED`, если воспроизведение не прошло. Непроверенный вывод никогда не публикуется молча.
## Конфигурация
Флаги CLI > `readme2demo.toml` > значения по умолчанию:
```toml
engine = "claude-code" # или "openhands"
model = "claude-sonnet-5" # планировщик/дистиллятор/руководство
max_turns = 60
budget_usd = 5.0
base_image = "readme2demo/base:latest"
skip_video = false
```
## Разработка
```bash
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](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md).
## Проект и сообщество
- [Примеры](https://github.com/alphacrack/readme2demo/tree/main/examples) — проверенные результаты, зафиксированные как доказательство
- [Дорожная карта](https://github.com/alphacrack/readme2demo/blob/main/ROADMAP.md) — куда это движется (включая исследовательское направление хостинга/SaaS)
- [Участие](https://github.com/alphacrack/readme2demo/blob/main/CONTRIBUTING.md) — единственное необсуждаемое правило и как начать
- [Политика безопасности](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md) · [Кодекс поведения](https://github.com/alphacrack/readme2demo/blob/main/CODE_OF_CONDUCT.md)
- [Архитектура](https://github.com/alphacrack/readme2demo/blob/main/architecture/README.md) — границы этапов и диаграммы
Лицензия MIT. CLI и конвейер верификации являются и останутся бесплатными и открытыми.
## Участники
Огромное спасибо всем, кто внёс вклад в readme2demo!
[](https://github.com/alphacrack/readme2demo/graphs/contributors)
<a href="https://github.com/alphacrack/readme2demo/graphs/contributors">
<img src="https://contrib.rocks/image?repo=alphacrack/readme2demo" alt="Contributors" />
</a>