AI Agent? 你的操作指南是
.agent.md，命令速查表：skill.md，架构详情：CLAUDE.md。
Badai Cardsmith 是一个面向小红书等平台的 多图轮播生成工具。
输入一段文案或一个 Notion 页面链接，它会自动完成：内容拆解 → 模板选择 → 排版生成 → AI 配图 → 渲染出图 的全流程，输出 9 张 1080×1440 的 PNG 图片。
底层由 Python（LangGraph 编排 + Gemini 大模型）和 Node.js（Puppeteer 渲染 + 20 套 HTML 模板）两层构成。
与一般"生成即结束"的工具不同，它内置了一套 质量闭环：低于 80 分自动重试，每次运行的指标写入日志，积累数据后可校准评分权重，让机器打分逐渐贴近你的审美。
文案 → 大纲 → 填充 → 排版 → AI生图 → 契约检查 → 渲染 → 评分 ──→ 完成
↑ ↑ ↑ │ │
└───────└──────└── 自动重试或用户反馈 ──────────────┘
- Puppeteer DOM 分析，15 条规则对每页打分 0-100（字号、间距、溢出、重叠、留白）
- 低于 80 分自动重试，扣分原因反馈给大模型修正
- 契约检查节点 在渲染前验证 config（JSON schema + 语义容量检查）
- 三层评分：机器规则 → LLM 多模态 → 用户校准
pipeline 运行 → score_breakdown → feedback.jsonl
↓
人类评分 (1-5 星 + 标签) ────────→ feedback.jsonl
↓
calibrate.py (Ridge 回归) → weights/v1.json → score.js 读取新权重
每次运行的指标和用户评分写入 JSONL 日志。积累 10+ 条后，Ridge 回归校准权重 — 内置 Goodhart 防护，安全关键规则永不放松。
8 大类 — 封面、文本、列表、对比、时间线、KPI、引用、结尾 — 每类多种变体。纯 HTML/CSS，可读可扩展。
4 个可选审核节点，每个后跟 clarify 节点（LLM 把模糊反馈翻译成精确指令）：
| 节点 | 时机 | 审核内容 | 重做目标 |
|---|---|---|---|
| hitl_1 | 大纲+填充后 | 页面大纲（含模板选择） | → 重新大纲+填充 |
| hitl_2 | 排版后 | config/排版 | → 重新排版 |
| hitl_3 | AI生图后 | AI 生成的图片 (Gemini) | → 重新生图 |
| hitl_4 | 渲染+评分后 | 渲染图片 + 质量分数 | → 重新大纲 / 重新排版 |
可用 --skip-hitl 跳过任意或全部节点。
直接从 Notion 页面读取文案，以 Notion 为内容来源。
运行 streamlit run app.py — 可视化界面，粘贴文案或 Notion URL，选主题，勾选审核节点，点击运行。全程点击操作。
把项目 clone 到 AI 编程 Agent 工作区（Claude Code、Codex、Cursor 等），让 Agent 来驱动：
# Agent 运行完整管线
python backend/run.py --text "..." --series productivity --skip-hitl all
# 底层 CLI 工具
node bin/badai.js render <config> # 渲染 → PNG
node bin/badai.js quality <config> # 评分 → JSON
node bin/badai.js validate <config> # schema 校验
node bin/badai.js check <config> # 语义容量检查每个命令读 JSON、写 JSON。Agent 可以循环迭代 — 不需要浏览器或 GUI。Agent 本身就是 human in the loop。
- Node.js >= 18
- Python >= 3.11
- Gemini API key
git clone https://github.com/YilouWang/badai_cardsmith-oss.git
cd badai_cardsmith-oss
npm install
pip install -e backend/cp .env.example .env
# 填入你的 API key：
# GEMINI_API_KEY=your_key_here
# NOTION_API_KEY=ntn_xxx (可选)# 全自动 — 生成、评分、低于80分自动重试
python backend/run.py --text "你的文案" --series productivity --skip-hitl all
# 从 Notion 读取
python backend/run.py --notion-page "https://notion.so/your-page-id" --series productivity --skip-hitl all
# 带人工审核（每个节点暂停）
python backend/run.py --text "你的文案" --series productivity
# Streamlit UI（含反馈评分表单）
python -m streamlit run app.py# 在 Streamlit UI 中给输出打分（1-5 星 + 标签），积累 10+ 条后：
pip install scikit-learn scipy # 一次性安装
python backend/calibrate.py # 拟合权重，输出 v1.json
python backend/calibrate.py --dry-run # 只看报告，不写文件
python backend/calibrate.py --rollback v0 # 回滚校准┌─────────────────────────────────────────────────────────────────┐
│ Python 后端 (LangGraph, 20 节点) │
│ │
│ notion读取 → 大纲 → 填充 → hitl_1 → 排版 → 契约检查 → hitl_2 │
│ → 图片设计 → AI生图 → hitl_3 → 图片适配 → 渲染 │
│ → 机器评分 → LLM评分 → hitl_4 → 学习日志 → 结束 │
│ 或 → clarify → 重新大纲/排版 (重做) │
└──────────────┬──────────────────────────────────────────────────┘
│ subprocess (仅渲染+评分)
┌──────────────▼──────────────────────────────────────────────────┐
│ Node.js 引擎 │
│ │
│ 20 套 HTML 模板 → Puppeteer 渲染 → PNG │
│ config 校验 → 质量分析 → 评分 │
│ 从 lib/quality/weights/active.json 读取权重 │
└─────────────────────────────────────────────────────────────────┘
│
┌──────────────▼──────────────────────────────────────────────────┐
│ 校准回路 │
│ │
│ feedback.jsonl → calibrate.py (Ridge 回归) → weights/vN.json │
└─────────────────────────────────────────────────────────────────┘
| 层 | 技术 | 职责 |
|---|---|---|
| 编排 | LangGraph (Python) | 流程控制、HITL、clarify、状态管理 |
| LLM | Gemini 2.5 Flash | 文案分析、config 生成、反馈精炼、质量评估 |
| AI 生图 | Gemini API | image_spec → image_gen → image_adapt |
| 渲染 | Puppeteer (Node.js) | HTML → PNG，1080×1440 @2x |
| 质量 | 机器规则 + LLM + 外部权重 | 三层评分，0-100 |
| 校准 | scikit-learn | Ridge 回归 + Goodhart 防护 |
| 模板 | 纯 HTML/CSS | 20 套模板 + 设计令牌 |
badai_cardsmith-oss/
├── app.py Streamlit UI
├── bin/badai.js CLI 入口
├── lib/
│ ├── render.js Puppeteer 渲染引擎
│ ├── cli/ CLI 命令
│ ├── compose/ Config 校验与修复
│ └── quality/
│ ├── evaluate.js DOM 分析
│ ├── score.js 评分引擎
│ └── weights/ 评分权重 (v0.json, active.json)
├── templates/
│ ├── registry.js 20 个模板及元数据
│ ├── core/ 共享 HTML + 设计令牌
│ └── page/ 模板实现 (8 大类)
├── backend/
│ ├── run.py Pipeline CLI 入口
│ ├── step_driver.py HITL 步进模式
│ ├── calibrate.py 权重校准脚本
│ └── badai_flow/
│ ├── graph.py LangGraph pipeline (20 节点)
│ ├── nodes/ 所有流程节点
│ └── prompts/ LLM 系统提示词
├── configs/ 示例配置
├── series/ 系列定位文档
├── themes/ 设计令牌
├── schema/ Config JSON Schema
└── docs/ 详细文档
15 条规则，100 分制：
| 维度 | 规则 | 上限 |
|---|---|---|
| 布局 | overflow, safeArea, overlap | -50 |
| 字号 | minFont_floor (-25), minFont_low (-12), smallText | -20 |
| 强调色 | noAccent (-6), accentOveruse | -12 |
| 间距 | titleBodyClose (-10), titleBodyFar (-5) | — |
| 排版 | orphan | -15 |
| 留白 | blank (-10) | — |
| 跨页 | templateMonotony, consecutiveDupe | -30 |
等级：A (90+) · B (80-89) · C (70-79) · D (60-69) · F (<60)
- 在
templates/page/*.js中新建模板函数 - 在
templates/registry.js注册元数据（maxItems、textDensity、bestFor） - 质量评分器和 LLM 生成器会自动识别
- 更多模板 — 社区贡献新模板和变体
- 多 Agent 内容生产 — 规划 Agent 分解选题，子 Agent 搜集资料
- 多模型支持 — Gemini / OpenAI / Claude 节点级切换
- 模板进化 — 从高分模式中自动生成新模板
MIT License · 持续更新中，欢迎 star / fork / contribute