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]'.
• اختياري: 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 مع حالات المراحل والتكلفة الإجمالية.

إجراء GitHub — تحقق من README الخاص بك في CI

احصل على علامة X حمراء عندما يتوقف README الخاص بك عن العمل. يقوم الإجراء المركب لجذر المستودع بتثبيت readme2demo من النسخة المثبتة الخاصة به، وبناء صورة البيئة الرملية، وتشغيل الأنابيب الكاملة مقابل عنوان URL الخاص بمستودعك، و يفشل الفحص عندما لا يمر إعادة التشغيل في الحاوية النظيفة:

name: readme-check
on:
  push:
    branches: [main]        # url mode tests the default branch HEAD — see the caveat below
    paths: ["README.md"]
  schedule:
    - cron: "0 6 * * 1"     # weekly: catch the world changing under an unchanged README

permissions:
  contents: read

jobs:
  verify-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: alphacrack/readme2demo@main   # pin a tag or SHA once released
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          skip-video: "true"

⚠ وضع URL فقط — هذا لا يتحقق من رؤوس طلبات السحب (PR) حتى الآن. يقوم الإجراء باستنساخ رأس الفرع الافتراضي البعيد لـ repo-url (افتراضيًا: المستودع الذي يشغّل سير العمل)؛ يقبل التحميل URLs https فقط، --depth 1، بدون تثبيت مرجع. في pull_request سيختبر README الفرع الأساسي — وليس README الخاص بـ PR — لذا لا تقم بتوصيله بـ PRs متوقعًا حكمًا قبل الدمج. حتى يصل #74 (تحميل المسار المحلي)، فإن on: push على الفرع الافتراضي و cron هما المشغلات الصادقة؛ سيصل إدخال repo-path للتحقق الحقيقي من رأس 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 الموثّق كخطوة مرقمة مع مخرجات حقيقية ملتقطة — ثم تبني الفيديو منه. جاهز للمساهمة به مرة أخرى في المستودع.

يتم توثيق خطوات الإعداد (الاستنساخ، التثبيت، البناء) في الدليل ولكن تُبقي خارج الفيديو — يعمل الفيديو ضد شجرة العمل الموثّقة والمبنية بالفعل، مع إظهار النتائج.

يحمل كل دليل تعليمي شارة تحقق: ✅ تم التحقق في <date> · image <digest> · commit <sha> — أو شارة ⚠ غير موثّق بصوت عالٍ إذا لم يمر إعادة التشغيل. لا يتم نشر المخرجات غير الموثّقة بصمت.

الإعدادات

أعلام CLI > readme2demo.toml > الإعدادات الافتراضية:

engine = "claude-code"      # or "openhands"
model = "claude-sonnet-5"   # planner/distiller/tutorial passes
max_turns = 60
budget_usd = 5.0
base_image = "readme2demo/base:latest"
skip_video = false

التطوير

python -m pytest tests/ -q            # 175 unit tests, no docker/network needed
ruff check src/ tests/               # correctness lint (matches CI)
python -m pytest -m integration      # requires docker + API keys (none yet)

نموذج الأمان

ملفات README ليست موثوقة. يعمل الوكيل داخل حاوية محصّنة (cap-drop ALL، no-new-privileges، حدود الذاكرة/المعالج/العمليات، غير الجذر) — هذه الحاوية هي حدود الإذن. المقايضة المعروفة في MVP: مفتاح API يدخل البيئة الرملية؛ استخدم مفتاحًا مخصصًا بحد منخفض. يتم التخطيط لوكيل خروج من الجانب المضيف لحقن المفاتيح (Milestone 4).

نموذج التهديد الكامل وإبلاغ الثغرات الخاصة: SECURITY.md.

المشروع والمجتمع

• أمثلة — مخرجات موثّقة مرفوعة كدليل
• خريطة الطريق — إلى أين يتجه هذا (بما في ذلك التوجيه الاستكشافي للاستضافة/SaaS)
• المساهمة — القاعدة الوحيدة غير القابلة للتفاوض، وكيفية الإعداد
• سياسة الأمان · مدونة السلوك
• البنية — حدود المراحل والرسوم البيانية

مرخصة بموجب MIT. سطر الأوامر وأنابيب التحقق هي، وستظل، مجانية ومفتوحة المصدر.

المساهمون

شكر كبير لكل من ساهم في readme2demo!