SVGLoop

Generate reliable SVG infographics with a coding agent, visual reviewers, and repair loop.

SVGLoop 的核心目标是把人类从反复检查和反馈的循环中解放出来。对于 SVG 信息图生成任务，用户只需要给出需求，系统会持续调用 Claude Code/Codex 生成与修复 SVG，再让多个视觉智能体审查 SVG 渲染效果，把视觉问题转化为下一轮可执行的修改方向。这个 Loop 会不断推进作品，直到通过预设检查或达到迭代上限。

Demo Gallery

_{Transformer 多头注意力 · 自动化代码智能体闭环}

_{视频平台架构 · 咖啡生产链}

这些 Demo 使用 Claude Code + GLM-5.2 作为代码智能体生成，并由 GPT-5.5、Qwen-3.7-plus 和 Gemini 3.1 Pro 作为 VLM 进行审查。

Core Idea

SVGLoop 采用 Ralph-style 外部循环：先生成，再渲染，再审图，再修复。使用主流 coding agent cli 生成 SVG 源码，然后调用来自不同厂商的多个VLM，从总体、细节、美观三个角度检查 SVG 渲染后的问题。

任务 prompt
  -> 代码智能体编写 current.svg
  -> 渲染为 current.png
  -> 规则检查 + 三类视觉智能体审图
  -> 汇总 feedback.json
  -> 代码智能体修复，直到通过或达到轮数上限

Why SVGLoop

• 兼容主流 coding agent：支持 Claude Code 和 Codex，适合直接交给 AI agent 调用。
• 补上代码模型的视觉闭环：为 GLM-5.2、Deepseek-V4-Pro 等缺乏多模态能力的代码模型提供视觉审查，提升 SVG 绘制能力。
• 多 VLM 交叉审查：可接入多个 OpenAI-compatible VLM API，减少单一 VLM 的偏见和幻觉影响，并从更多角度评测 SVG。
• 可复现的自动 Loop：每轮保留 SVG、PNG、反馈和最终产物，方便检查、续跑和复现实验。

Quick Start

需要准备：

• Python 3.10+
• Claude Code CLI 或 Codex CLI，至少一个位于 PATH
• Chrome/Chromium，或可用的 CairoSVG/ImageMagick 渲染 fallback
• 一个 OpenAI-compatible VLM API，用于视觉审查

git clone https://github.com/strangersinsist/SVGLoop svgloop
cd svgloop
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .
svgloop doctor
svgloop run "绘制 SVG 信息图，展示 Transformer 多头注意力的计算流程"

空白机器安装、Chrome/ImageMagick fallback、Claude Code/Codex CLI 配置等细节见 .agents/docs/INSTALL.md。给 agent 使用时，优先让它阅读 .agents/skills/svgloop/SKILL.md。

配置

主程序会自动读取仓库根目录下的 .env，已有 shell 环境变量优先。以 .env.example 为模板创建本地配置：

cp .env.example .env

最小配置示例：

SVGLOOP_WRITER_BACKEND=claude
SVGLOOP_WRITER_MODEL=glm-5.2

SVGLOOP_REVIEW_AGENTS=model1
SVGLOOP_REVIEW_AGENT_MODEL1_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
SVGLOOP_REVIEW_AGENT_MODEL1_API_KEY=your-gemini-api-key
SVGLOOP_REVIEW_AGENT_MODEL1_MODEL=gemini-3.1-pro

Writer backend 支持 claude 和 codex，默认是 claude。使用 Codex 作为写图 agent 时可设置 SVGLOOP_WRITER_BACKEND=codex；如需指定 Codex 模型，可设置 SVGLOOP_CODEX_MODEL 或命令行 --writer-model，不设置则使用 Codex CLI 自己的默认模型。

最多可配置三个 VLM reviewer；本文实验配置参考 .env.example，分别是 gpt-5.5、gemini-3.1-pro-high 和 qwen3.7-plus。如果只配置一个 VLM，推荐使用 gemini-3.1-pro。

每个 alias 都需要以下三项：

SVGLOOP_REVIEW_AGENT_<ALIAS>_BASE_URL
SVGLOOP_REVIEW_AGENT_<ALIAS>_API_KEY
SVGLOOP_REVIEW_AGENT_<ALIAS>_MODEL

.env 含密钥，仅保存在本地；.env.example 是不含真实密钥的配置模板。

使用方式

在项目根目录运行：

svgloop run "绘制 SVG 流程图，展示从一颗咖啡豆到一杯咖啡的完整生产链"

更推荐对复杂任务使用 brief 文件，让外层 agent 只整理上下文，具体视觉设计交给 SVGLoop：

svgloop run \
  --prompt-file brief.md \
  --context-dir ./resources \
  --output-dir .svgloop/runs \
  --final ./figures/result.svg \
  --final-png ./figures/result.png \
  --no-stream-agents \
  --json

指定固定案例名：

svgloop run --name coffee_chain "绘制 SVG 流程图，展示从一颗咖啡豆到一杯咖啡的完整生产链"

常用参数：

svgloop run --case word_embedding \
  --max-iters 4 \
  --min-review-total 95 \
  --writer-timeout 3600 \
  --review-timeout 1800 \
  --reviewer-retries 30 \
  --review-parallelism 3

参数	作用
--prompt-file	从 Markdown/text 文件读取任务 brief，适合长需求或 agent 调用。
--context-dir	允许内部 Writer 读取的资源目录，可重复传入多个目录。
--output-dir	运行产物目录，默认读取 SVGLOOP_OUTPUT_DIR 或写入当前目录的 .svgloop/runs/。
--final	单任务完成后，把选中的最终 SVG 复制到指定路径。
--final-png	单任务完成后，把选中的最终 PNG 复制到指定路径。
--json	结束时输出机器可读摘要，便于 Codex/Claude 解析。
--writer-backend	写图 coding agent 后端，可选 claude 或 codex，默认读取 SVGLOOP_WRITER_BACKEND 或 claude。
--writer-model	传给 writer backend 的模型名；Claude 默认读取 SVGLOOP_WRITER_MODEL，Codex 默认读取 SVGLOOP_CODEX_MODEL 或使用 Codex CLI 默认模型。
--max-iters	最大 Writer-Reviewer 迭代次数，默认 4。
--min-review-total	允许质量通过的 VLM 总分阈值，默认 95。
--writer-timeout	单轮 Writer 超时秒数。
--review-timeout	每个 VLM 调用的超时秒数。
--reviewer-retries	VLM 返回失败或格式不合法时的重试次数。
--review-parallelism	VLM 调用并发数。
--review-lenses	审图视角，默认 global,defect,composition。
--allow-websearch	允许 Writer 使用 web search。
--no-stream-agents	不在终端实时输出 agent 活动。
--resume-run PATH	从既有 run 目录继续未完成任务。
--dry-run	不调用真实模型，只验证主流程和产物目录。
--baseline single	仅运行首轮 Writer，不进入修复循环。

未安装 CLI 时，也可以从项目根目录直接运行：

python ralph_svgloop.py run --prompt-file brief.md --json

Agent Skill

SVGLoop 适合作为 Claude Code 或 Codex 的可复用工具。推荐把 skill 作为薄封装安装，核心生成能力仍由 CLI 负责。

通用 skill 模板放在：

.agents/skills/svgloop/SKILL.md

需要全局使用时，可以将通用 skill 复制或软链接到个人 skills 目录，例如：

svgloop install-skill --target all

默认使用软链接；如需复制而不是软链接，可加 --copy。目标已存在时可加 --force 覆盖。

Skill 的调用边界是：外层模型只负责整理 brief、选择 --context-dir 和读取结果；不要让外层模型手工设计 SVG 的布局、颜色、图标和坐标，这些由 SVGLoop 的 Writer-Reviewer 闭环完成。

项目文件

svgloop/
├── README.md                         # 项目说明文档
├── AGENTS.md                         # 面向 Claude Code/Codex 等 coding agent 的项目操作指南
├── CLAUDE.md                         # Claude Code 入口，转向 AGENTS.md 并声明硬规则
├── pyproject.toml                    # editable install 与 svgloop 命令入口
├── ralph_svgloop.py                  # 唯一运行入口：调度 Writer、渲染、规则检查、VLM 审图和报告生成
├── .env                              # 本机 Writer/VLM 配置与密钥
├── .env.example                      # 配置模板，展示本文实验使用的三个 VLM reviewer
├── .gitignore                        # 忽略本机密钥、缓存和生成产物
├── .agents/                          # 面向 AI coding agent 的分层知识库和工作流
│   ├── docs/                         # 人类和 agent 共用的安装、架构与使用文档
│   │   ├── INSTALL.md                # 空白机器安装、doctor 排障和 smoke test
│   │   └── ARCHITECTURE.md           # 代码结构、运行生命周期、不变量和扩展点
│   ├── knowledge/                    # agent 常驻知识：原则、约束、架构、文档维护
│   └── skills/                       # agent 任务技能和可安装的 SVGLoop end-user skill
│       ├── svgloop/                  # 可安装到 ~/.codex/skills 或 ~/.claude/skills 的通用 skill
│       └── svgloop-develop/          # 仓库内修改源码、文档和打包配置的 agent 工作流
├── agents/                           # Writer 与 Reviewer 提示词
│   ├── writer_initial.md             # 首轮 Writer 约束：先写计划，再创建完整 SVG
│   ├── writer_repair.md              # 修复轮 Writer 约束：根据规则结果和 VLM 反馈修复 SVG
│   ├── reviewer.md                   # VLM reviewer 共用审图任务与 JSON 输出格式
│   ├── reviewer_global.md            # 语义、内容完整性和叙事主线审查视角
│   ├── reviewer_defect.md            # 文字裁剪、重叠、乱码、连线碰撞等硬缺陷审查视角
│   └── reviewer_composition.md       # 对齐、留白、平衡、节奏与视觉完成度审查视角
├── tools/                            # 确定性工具模块
│   ├── __init__.py                   # Python 工具包标记
│   ├── artifacts.py                  # 检查 SVG 写入，并保存、恢复每轮快照及最终文件
│   ├── feedback_schema.py            # 解析、校验和规范化 VLM 返回的 JSON 反馈
│   ├── render_svg.py                 # 将 SVG 渲染为 PNG，优先 Chrome/Chromium，并提供 fallback
│   ├── report.py                     # 根据 run_log.json 生成单次运行的 report.md
│   ├── review_lenses.py              # 读取审图视角模板并组装 reviewer prompt
│   ├── rule_check.py                 # 对 SVG 做边界、文本风险和结构问题等确定性检查
│   ├── runtime_log.py                # 终端实时输出与运行日志的格式化辅助函数
│   └── svg_sanitize.py               # 提取 SVG，禁止脚本/外部资源，并处理高风险字符
├── cases/                            # 内置案例
│   ├── required_cases.json           # 五个标准案例，供 --case 与 --all 使用
│   └── extra_cases.json              # 补充案例提示词，仅作实验资料
├── assets/                           # 当前报告引用的展示素材
│   ├── *_final.svg                   # 精选最终 SVG
│   ├── llm_iter*.png                 # LLM 原理案例的迭代对比图
│   └── *-compare.png                 # 校史、直播电商、城市碳循环案例的对比图
└── runs/                             # 历史实验运行目录；新任务默认不再写入这里

.svgloop/
└── runs/                             # 默认运行产物目录；可用 --output-dir 覆盖

默认情况下，每个 reviewer 都会分别执行 global、defect 和 composition 三个视角的审查，然后由主程序聚合反馈。__pycache__/ 是 Python 运行时缓存，不属于项目源码结构。

单次运行产物

每次运行默认会写入 .svgloop/runs/<timestamp>_<case_name>/；也可以通过 --output-dir 指定其他目录：

.svgloop/runs/<timestamp>_<case_name>/
  task.md                    # 本次任务文本
  STATE.md                   # 当前轮的状态与待修复问题
  current.svg / current.png  # 当前 SVG 及渲染结果
  final.svg / final.png      # 评分最好的最终版本
  rule_check.json            # 确定性规则检查结果
  visual_feedback.json       # VLM 的原始聚合视觉判断
  feedback.json              # 与规则结果融合后的修复反馈
  run_log.json               # 机器可读的完整运行状态
  run_events.md              # 人类可读流程日志
  report.md                  # 自动生成的单次运行报告
  writer_plan.md             # 首轮 Writer 计划
  writer_repair_plan.md      # 修复轮 Writer 计划
  iterations/                # 每轮 SVG、PNG、规则与反馈快照
  agent_logs/                # Writer 与 reviewer 的 prompt、输出和调用日志

历史 runs/ 仅用于复盘或通过 --resume-run 恢复任务，不是启动新任务的必需输入。