readme2demo v0.7.5
دروس تعليمية وفيديوهات توضيحية موثقة من ملف README الخاص بك. يقوم وكيل ذكاء اصطناعي بتشغيلها في بيئة اختبار معزولة ومحصنة (Docker sandbox)، ويعيد تشغيلها في حاوية جديدة قبل نشر أي شيء.
readme2demo — دروس تعليمية موثقة وفيديوهات عرض توضيحي من ملف README الخاص بك
▶ readme2demo يُنشئ دليله التعليمي الخاص: وكيل ذكاء اصطناعي يشغّل ملف README الخاص بهذا المستودع في بيئة رملية، ثم يعيد حاوية جديدة تشغيل كل خطوة، ثم يتم عرض العرض التوضيحي. مخرجات التشغيل الذاتي الكاملة في examples/readme2demo · شغّله على مشروع آخر في examples/toolhive.
مولّد دروس تعليمية وفيديوهات عرض توضيحي تم التحقق منها بواسطة الذكاء الاصطناعي. وجّهه إلى مستودع. يقرأ وكيل ذكاء اصطناعي ملف README وينفذه فعليًا داخل بيئة رملية معزّزة (Docker). فقط بعد أن يمرّ إعادة تشغيل في بيئة نظيفة بنجاح، يقوم بعرض فيديو توضيحي (VHS) ونشر الدليل التعليمي، ودليل الخطوات خطوة بخطوة، ووثيقة استكشاف الأخطاء وإصلاحها.
القيمة ليست في أن "الذكاء الاصطناعي يكتب دليلاً تعليميًا" — بل في أن الدليل تم تشغيله، مرتين، قبل أن تراه.
شاهده أثناء العمل: تصفّح عمليات تشغيل نموذجية تم التحقق منها — دروس تعليمية حقيقية، وأدلة خطوة بخطوة، وفيديوهات عرض توضيحي، كل منها تم إعادة تشغيله بشكل مستقل في حاوية نظيفة قبل النشر.
كيف يعمل
repo URL → ingest/plan → agent run (in Docker) → normalize transcript
→ distill minimal path → VERIFY replay in fresh container
→ generate tutorial.md + troubleshooting.md → render VHS video
انظر 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]'.
- اشتراك Claude الخاص بك (بدون مفتاح API): تثبيت محلي لـ Claude Code. يتم تشغيل عمليات المخطط/المقطّر/الدليل التعليمي على اشتراكك عبر
- اختياري:
LLM_API_KEY+LLM_MODELلـ--engine openhands(تجريبي) مع أي مزود litellm آخر — الإعدادات المسبقة أعلاه تملؤها تلقائيًا
# run on your Claude subscription (no API key) — supported for self-hosted runs
claude setup-token # interactive: approve in browser, then COPY the
# sk-ant-oat01-... token it prints (do NOT use $(...))
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
readme2demo run <repo-url> --llm-backend claude-cli
# run on metered API billing (scale, concurrency, or hosting for others)
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url> # --llm-backend auto picks api
# run the whole session on Google Gemini (OpenHands agent + Gemini passes)
pip install 'readme2demo[gemini]'
docker build -t readme2demo/openhands:latest images/openhands # one-time: OpenHands sandbox image
export GEMINI_API_KEY=...
readme2demo run <repo-url> --gemini gemini-3.5-flash # model named per run
export GEMINI_MODEL=gemini-3.5-flash # ...or set once, then:
readme2demo run <repo-url> --gemini # bare flag reads GEMINI_MODEL
# run the whole session on OpenAI (OpenHands agent + OpenAI passes)
pip install 'readme2demo[openai]'
export OPENAI_API_KEY=sk-...
readme2demo run <repo-url> --openai gpt-5.1 # or export OPENAI_MODEL once
# run the OpenHands agent with a Claude model on API billing
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url> --anthropic # uses the config model by default
التثبيت
pip install -e ".[dev]"
docker build -t readme2demo/base:latest images/base/
docker build -t readme2demo/openhands:latest images/openhands/ # only for --engine openhands / --gemini / --openai / --anthropic
الاستخدام
readme2demo run https://github.com/example/tool
readme2demo run -gr https://github.com/example/tool # same, via the flag
readme2demo run -s my_guide.md # guide-only: no repo, your guide is self-contained
readme2demo run -gr https://github.com/example/tool -s my_guide.md # both: your guide drives everything
readme2demo run https://github.com/example/tool --gemini gemini-3.5-flash # run on Google Gemini (needs GEMINI_API_KEY; uses the OpenHands agent; bare --gemini reads GEMINI_MODEL)
readme2demo run https://github.com/example/tool --openai gpt-5.1 # run on OpenAI (needs OPENAI_API_KEY; uses the OpenHands agent; bare --openai reads OPENAI_MODEL)
readme2demo run https://github.com/example/tool --anthropic # OpenHands agent with a Claude model on ANTHROPIC_API_KEY
readme2demo run https://github.com/example/tool --allow-docker-socket # for tools that manage containers (SECURITY TRADEOFF: pierces sandbox isolation — trusted repos only)
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 مع حالات المراحل والتكلفة الإجمالية.