alphacrack/readme2demoREADME에서 검증된 튜토리얼 및 데모 비디오입니다. AI 에이전트가 강화된 Docker 샌드박스에서 이를 실행하고, 게시되기 전에 새로운 컨테이너에서 다시 실행합니다.
▶ readme2demo가 자신의 튜토리얼을 생성하는 과정: AI 에이전트가 이 리포지토리의 README를 샌드박스에서 읽고, 새로운 컨테이너에서 모든 단계를 다시 실행한 후 데모를 렌더링합니다. 전체 자체 실행 결과는 examples/readme2demo 에서 확인 · 다른 프로젝트에 대해 실행한 결과는 examples/toolhive 에서 확인.
AI 검증 튜토리얼 및 데모 비디오 생성기. 리포지토리를 가리키세요. AI 에이전트가 README를 읽고 강화된 Docker 샌드박스 내에서 실제로 실행합니다. 클린룸 재현이 통과된 후에만 데모 비디오 (VHS)를 렌더링하고, 튜토리얼, 단계별 가이드, 문제 해결 문서를 게시합니다.
가치는 "AI가 튜토리얼을 작성한다"는 것이 아니라, 여러분이 보기 전에 튜토리얼이 두 번 실행되었다는 점입니다.
직접 확인하세요: 검증된 예제 실행 결과를 살펴보세요 — 실제 튜토리얼, 단계별 가이드, 데모 비디오가 각각 깨끗한 컨테이너에서 독립적으로 재현되어 게시되었습니다.
리포지토리 URL → 수집/계획 → 에이전트 실행 (Docker 내) → 트랜스크립트 정규화
→ 최소 경로 추출 → 검증: 신규 컨테이너에서 재현
→ tutorial.md + troubleshooting.md 생성 → VHS 비디오 렌더링
전체 아키텍처는 architecture/README.md를 참조하세요.
--llm-backend claude-cli (claude -p)를 통해 구독으로 실행되며, 샌드박스 내 에이전트는 CLAUDE_CODE_OAUTH_TOKEN으로 인증합니다 (생성: claude setup-token). 자가 호스팅, 단일 운영자가 자신의 리포지토리에 대해 실행하는 경우 완전 지원 — Pro/Max 플랜에는 claude -p를 포함하는 월간 Agent SDK 크레딧이 포함되어 있습니다.ANTHROPIC_API_KEY — 사용량 기반 API 과금; 규모 및 동시성에 가장 적합하며, readme2demo를 서비스로 제공하는 경우 필수 (Anthropic 이용 약관에 따라 구독 인증으로는 멀티 테넌트 제품을 구동할 수 없음 — ROADMAP.md 참조). --anthropic [모델]을 추가하면 claude-code 대신 OpenHands 엔진에서 Claude 모델로 샌드박스 에이전트를 실행합니다.--gemini [모델]): 단일 GEMINI_API_KEY로 전체 세션을 Claude 없이 실행합니다 — 계획/추출/튜토리얼 단계는 Gemini를 사용하고 샌드박스 에이전트는 OpenHands 엔진 (역시 Gemini)에서 실행됩니다. 내장 모델 이름은 없습니다 (Google은 이전 모델을 하드 404로 폐기합니다): 실행 시 이름 지정 (--gemini gemini-3.5-flash) 또는 을 한 번 내보내기. 추가 패키지 설치: .# Claude 구독으로 실행 (API 키 불필요) — 자체 호스팅 실행 지원
claude setup-token # 대화형: 브라우저에서 승인한 후, 출력된
# sk-ant-oat01-... 토큰을 복사하세요 ($(...)) 사용 금지
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
readme2demo run <리포지토리-URL> --llm-backend claude-cli
# 사용량 기반 API 과금으로 실행 (규모, 동시성, 또는 타인 호스팅)
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <리포지토리-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 <리포지토리-URL> --gemini gemini-3.5-flash # 실행 시 모델 이름 지정
export GEMINI_MODEL=gemini-3.5-flash # ...또는 한 번 설정 후:
readme2demo run <리포지토리-URL> --gemini # 플래그만 사용하면 GEMINI_MODEL 읽음
# 전체 세션을 OpenAI로 실행 (OpenHands 에이전트 + OpenAI 단계)
pip install 'readme2demo[openai]'
export OPENAI_API_KEY=sk-...
readme2demo run <리포지토리-URL> --openai gpt-5.1 # 또는 OPENAI_MODEL을 한 번 내보내기
# API 과금으로 OpenHands 에이전트를 Claude 모델과 함께 실행
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <리포지토리-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 # ANTHROPIC_API_KEY로 OpenHands 에이전트를 Claude 모델과 함께 실행
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.
README가 작동을 멈출 때 빨간 X를 받으세요. 리포지토리 루트의 복합 액션은 자체 고정 체크아웃에서 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 모드 전용 — 아직 PR 헤드를 검증하지 않습니다. 이 액션은
repo-url(기본값: 워크플로우를 실행하는 리포지토리)의 원격 기본 브랜치 HEAD를 클론합니다; 수집은 https URL,--depth 1, 리비전 고정 없이만 허용합니다.pull_request이벤트에서는 PR의 README가 아니라 베이스 브랜치의 README를 테스트합니다 — 따라서 병합 전 판정을 기대하며 PR에 연결하지 마십시오. #74 (로컬 경로 수집)가 적용될 때까지, 기본 브랜치에 대한on: push와 cron이 정직한 트리거입니다; 실제 PR 헤드 검증을 위한repo-path입력은 그때 함께 제공됩니다.
비용: 각 실행은 ANTHROPIC_API_KEY로 실제 에이전트 비용을 지출합니다 — 일반적으로 몇 달러이며, budget-usd (기본값 "5"; 초과 시 실행 중단)로 상한이 설정됩니다. paths: 필터와 cron은 README 변경량에 비례하여 지출을 유지하고, skip-video: "true"는 벽시계 시간을 줄입니다 (렌더링은 어차피 API 비용이 들지 않습니다).
검사는 두 가지 구분 가능한 방식으로 실패하며, 단계 로그에 이름이 표시됩니다: README 손상 (파이프라인 완료, 클린룸 재현 실패 — readme2demo report --json을 통해 감지, readme2demo run은 완료되었지만 검증되지 않은 실행에 대해 의도적으로 0을 반환하기 때문) 및 액션 인프라 손상 (0이 아닌 파이프라인 종료: 사전 점검, 예산, Docker). 출력: verified ("true"/"false") 및 run-dir; tutorial.md, step_by_step.md, verify.log (비디오 켜져 있을 때 demo.gif)가 readme2demo-run 아티팩트로 업로드됩니다.
데모 비디오는 항상 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, memory/cpu/pids 제한, non-root) — 이 컨테이너가 권한 경계입니다. 알려진 MVP 트레이드오프: API 키가 샌드박스에 들어갑니다; 전용 저한도 키를 사용하세요. 호스트 측 키 주입 이그레스 프록시가 계획되어 있습니다 (마일스톤 4).
전체 위협 모델 및 비공개 취약점 보고: SECURITY.md.
MIT 라이선스. CLI 및 검증 파이프라인은 지금과 앞으로도 무료 오픈 소스입니다.
readme2demo에 기여해 주신 모든 분들께 진심으로 감사드립니다!
GEMINI_MODELpip install 'readme2demo[gemini]'--openai [모델]): Gemini와 동일한 형태 — 단일 OPENAI_API_KEY가 단계와 OpenHands 에이전트를 모두 구동하며, 내장 모델 이름은 없습니다 (--openai gpt-5.1 또는 OPENAI_MODEL 내보내기). 추가 패키지 설치: pip install 'readme2demo[openai]'.LLM_API_KEY + LLM_MODEL for --engine openhands (실험적) 다른 litellm 제공자와 함께 — 위의 프리셋이 자동으로 채웁니다.