readme2demo — 源自你的 README 的经过验证的教程与演示视频

_{▶ readme2demo 生成自己的教程：AI 代理在沙箱中运行此仓库的 README，一个全新容器重放每一步，然后渲染演示。完整自运行输出请见 examples/readme2demo · 针对另一个项目的运行请见 examples/toolhive。}

AI 验证的教程与演示视频生成器。 指向一个仓库。AI 代理会读取 README 并在加固的 Docker 沙箱中实际运行它。只有在干净环境重放通过后，它才会渲染演示视频（VHS）并发布教程、分步指南和故障排除文档。

其价值不在于“AI 写教程”——而在于教程在你看到之前已经运行了两次。

查看实际效果： 浏览已验证的示例运行 — 真实的教程、分步指南和演示视频，每个都在发布前于干净容器中独立重放。

工作原理

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 会以 hard 404 淘汰旧模型）：每次运行指定（--gemini gemini-3.5-flash）或一次性导出 GEMINI_MODEL。安装额外依赖：。

# 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 Action — 在 CI 中验证你的 README

当你的 README 停止工作时得到一个红色 X。仓库根目录的组合操作从自身的固定检出安装 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 的远程默认分支 HEAD（默认：运行工作流的仓库）；摄取仅接受 https URL，--depth 1，无 ref 固定。对于 pull_request，它会测试基础分支的 README —— 而不是 PR 的 —— 所以不要将其接入预期获得合并前判决的 PR。直到 #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 构建：解析其步骤，每个演示安全、有根据的命令都会成为视频中的一个键入命令，步骤标题显示为屏幕上的注释。它有三种生成方式（按优先级顺序）：

你传入一份：readme2demo run <url> -s my_guide.md — 注入到克隆中作为权威指南；规划器和代理遵循它，视频播放它。此处的 <url> 是可选的：readme2demo run -s my_guide.md 在空沙箱中仅运行指南。
仓库自带一份（根目录或 docs/ 下的 step_by_step.md / step-by-step.md，不区分大小写）：自动获得相同处理。
两者都不存在：流水线生成一份详细的 step_by_step.md —— 来自已验证的 commands.sh 的每条命令都作为带有实际捕获输出的编号步骤 —— 然后从中构建视频。随时可贡献回仓库。

设置步骤（克隆、安装、构建）会记录在指南中，但不出现在视频中 —— 视频针对已验证、已构建的工作树播放，展示效果。

每个教程都带有验证徽章：✅ Verified on <date> · image <digest> · commit <sha> —— 如果重放未通过，则显示醒目的 ⚠ UNVERIFIED。未验证的输出绝不会被静默发布。

配置

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、内存/CPU/进程数限制、非 root）——该容器是权限边界。已知 MVP 权衡：API 密钥进入沙箱；请使用专用的低限额密钥。计划实现主机侧密钥注入出口代理（里程碑 4）。

完整威胁模型和私有漏洞报告：SECURITY.md。

项目与社区

Examples — 作为证据提交的已验证输出
Roadmap — 项目发展方向（包括探索性的托管/SaaS 方向）
Contributing — 唯一不可协商的规则，以及如何开始
Security policy · Code of Conduct
Architecture — 阶段边界与图表

MIT 许可。CLI 和验证流水线现为且将保持自由和开源。

贡献者

衷心感谢所有为 readme2demo 做出贡献的人！

readme2demo

最受欢迎