# genui

**Repository Path**: lvhaodeyeye/genui

## Basic Information

- **Project Name**: genui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# genui

**genui** 是一个把"文字变图片"能力封装成单条命令的 CLI 工具，专为 AI Agent 设计，消除重复造轮子的 token 浪费。

两种调用模式：`-cg` 直接传代码或提示词渲染，`-lg` 只给自然语言由内置 LLM 生成代码后渲染。支持 HTML、Mermaid、TikZ 三种代码渲染，以及 Qwen / MiniMax / Gemini 图像生成模型。

Agent 只需一行命令完成出图，渲染逻辑完全下沉到工具层。

## 配套 Skill

genui 提供配套的 `genui-draw` skill，安装后 AI Agent（Claude Code、OpenClaw 等）可在对话中直接调用 genui 出图，无需手动拼命令。

**一键安装（推荐）**：对 OpenClaw 说：

```
fetch https://gitee.com/lvhaodeyeye/genui/blob/master/skills/genui-draw/references/install.md 内容，之后按照内容安装genui和skill
```

Agent 会自动完成 genui 安装和 skill 部署。安装完成后，用户需手动：
- 安装系统级依赖（Chromium、LaTeX 等，按需选择）
- 通过 `genui config` 配置图像生成模型的 API Key

---

## 概述

`genui` 支持两种工作模式：

- **`-cg`（code generate）**：直接提供代码或提示词，工具渲染为图片
- **`-lg`（language generate）**：用自然语言描述需求，内置 LLM agent 生成代码/提示词后渲染

支持 HTML、Mermaid、TikZ 三种代码渲染类型，以及调用图像生成模型（Qwen / MiniMax / Gemini）。

## 技术栈

- **语言**：Python 3.11+
- **CLI**：Typer + Click
- **交互配置**：InquirerPy + Rich
- **HTML 渲染**：Playwright（headless Chromium）
- **Mermaid/TikZ 渲染**：Kroki.io API（零本地依赖）+ 本地 fallback
- **HTTP**：httpx（异步）
- **打包**：hatchling + uv tool install

## 安装

```bash
uv tool install genui

# 首次使用前安装浏览器（HTML 渲染用）
playwright install chromium
```

## 外部依赖

`genui` 的 Python 包依赖由 `uv` 自动管理，但部分渲染后端需要**手动安装系统级外部程序**。

### HTML 渲染

| 依赖 | 必须 | 安装方式 |
|---|---|---|
| Chromium | ✅ | `playwright install chromium` |

### Mermaid 渲染

默认走 **Kroki.io 远程 API**（无需本地依赖）。网络不通时自动 fallback 到本地 `mmdc`。

| 依赖 | 必须 | 安装方式 |
|---|---|---|
| 网络（访问 kroki.io） | ✅（默认路径） | — |
| Node.js + mmdc | ⬜ 仅 fallback | `npm install -g @mermaid-js/mermaid-cli` |

### TikZ 渲染

默认走 **Kroki.io 远程 API**。`tikz_backend` 配置为 `local` 或 `auto`（且本地有 pdflatex）时走本地路径。

| 依赖 | 必须 | 安装方式 |
|---|---|---|
| 网络（访问 kroki.io） | ✅（默认路径） | — |
| pdflatex | ⬜ 仅 local/auto | macOS: `brew install --cask mactex-no-gui` · Linux: `apt install texlive-full` |
| Poppler | ⬜ 仅 local/auto | macOS: `brew install poppler` · Linux: `apt install poppler-utils` |

> **TikZ 库覆盖**：genui 内置 preamble 已加载 22 个常用 tikzlibrary（`shapes.geometric`、`automata`、`positioning`、`calc`、`3d`、`pgfplots` 等），用户/LLM 直接使用对应特性无需手动声明 `\usetikzlibrary`。

### 图像生成提供商

需在 `genui config` 中填入对应 API Key。

| 提供商 | API Key 来源 |
|---|---|
| Qwen / Wanx | [DashScope 控制台](https://dashscope.console.aliyun.com/) |
| MiniMax | [MiniMax 开放平台](https://www.minimaxi.com/user-center/basic-information/interface-key) |
| Gemini | [Google AI Studio](https://aistudio.google.com/apikey) |

## 使用

```bash
# 从 HTML 代码生成图片
genui generate -cg html -p "<h1>Hello</h1>" -o ./out.png -w 800 -H 600

# 从 HTML 文件生成截图（-i 直接读取文件内容，文件负责自身依赖完整性）
genui generate -cg html -i ./page.html -o ./screenshot.png -w 1280 -H 720

# 从自然语言生成 Mermaid 流程图
genui generate -lg mermaid -p "画一个用户注册流程图" -o ./flow.png

# 从文本文件读取描述生成 TikZ 图（-i 等价于将文件内容作为 -p 传入）
genui generate -lg tikz -i ./diagram_desc.txt -o ./figure.svg -t 120

# 从自然语言生成图片（带参考图）
genui generate -lg model -p "类似参考图的风格，画一只猫" -r ./ref.jpg -o ./cat.png

# 直接调用图像生成模型（使用默认 provider）
genui generate -cg model -p "a cat sitting on a windowsill, photorealistic" -o ./cat.png

# 直接调用图像生成模型（指定 provider/model，model 名可含 /）
genui generate -cg qwen/qwen-image-2.0-pro -p "a cat on a windowsill" -o ./cat.png
genui generate -lg gemini/gemini-3.1-flash-image-preview -p "a cat on a windowsill" -o ./cat.png

# TikZ 代码渲染
genui generate -cg tikz -p '\draw (0,0) -- (1,1);' -o ./diagram.svg

# 设置超时（-lg html 调用 LLM 生成完整 HTML，建议 -t 180 以上）
genui generate -lg html -p "复杂的数据可视化" -o ./chart.png -t 180

# 指定内置 LLM（-lm ALIAS，仅在 -lg 模式生效；ALIAS 来自 genui config --list 的 llms 段）
genui generate -lg html -lm deepseek-chat -p "一个按钮组件" -o ./btn.png -t 120

# 查看已配置的 provider 及模型
genui providers

# 交互式配置
genui config
```

## 参数说明

| 参数 | 简写 | 说明 |
|---|---|---|
| `--cg METHOD` | `-cg METHOD` | code generate 模式，METHOD 为渲染类型或 `provider/model_name` |
| `--lg METHOD` | `-lg METHOD` | language generate 模式，METHOD 同上 |
| `--prompt` | `-p` | 输入提示词或代码内容；与 `-i` 互斥，设置 `-i` 时被忽略 |
| `--input` | `-i` | 从文本文件读取内容。设置后 `-p` 失效。`-cg` 模式下文件内容直接传入渲染器（文件需自行保证依赖完整性，genui 不做任何加工）；`-lg` 模式下等价于将文件内容作为 `-p` 使用 |
| `--output` | `-o` | 输出文件路径（.png / .jpg / .webp / .svg） |
| `--width` | `-w` | 输出宽度（像素）；model 类型下 Gemini 忽略此参数 |
| `--height` | `-H` | 输出高度（像素）；model 类型下 Gemini 忽略此参数 |
| `--reference` | `-r` | 参考图路径（可多次指定） |
| `--timeout` | `-t` | 超时秒数；`-lg html` 建议 ≥ 180 |
| `--lm` | `-lm` | 指定内置 LLM 的配置 alias（仅 `-lg` 模式生效）；alias 名称见 `genui config --list` 的 `llms.*` 段 |

## 配置

配置文件：`~/.genui/config.json`

```bash
genui config   # 启动交互式配置向导
```

配置项包括：
- 内置 agent 使用的 LLM（base_url / model / API key / 是否支持视觉）
- 图像生成提供商（Qwen / MiniMax / Gemini），支持从预设模型列表选择或手动输入
- 配置完成后自动展示 curl 请求模板（key 已脱敏）供验证
- 自定义 system prompt（支持 Markdown 继承）

### 图像生成提供商

| 提供商 | 默认模型 | 备注 |
|---|---|---|
| **Qwen** | `qwen-image-2.0-pro` | `qwen-image-*`：multimodal-generation 接口（sync/async）；`wan*/wanx*`：text2image 接口（async） |
| **MiniMax** | `image-01` | `api.minimaxi.com`；`image-01-live` 自动转换为 `aspect_ratio` |
| **Gemini** | `gemini-3.1-flash-image-preview` | generateContent 接口；不支持指定输出尺寸，传入 `-w/-H` 会有 warn |

## 项目结构

```
genui/
├── pyproject.toml
├── README.md
├── CHANGELOG.md
├── feature.json
├── docs/
│   └── design.md          # 完整设计文档
└── src/
    └── genui/
        ├── cli.py          # CLI 入口
        ├── config/         # 配置管理 + 向导
        ├── renderers/      # HTML / Mermaid / TikZ / Model 渲染器
        ├── agent/          # 内置绘图 agent + prompt 继承管理
        └── providers/      # 图像生成 API 适配器（qwen / minimax / gemini）
```

详细设计见 [docs/design.md](docs/design.md)。

## 输出规范

工具仅打印极简信息：

```
[genui] rendering html...
[genui] saved: /path/to/output.png
```

## 参考项目

- [pi-generative-ui](https://github.com/Michaelliv/pi-generative-ui) — 本项目的灵感来源

## License

[MIT](./LICENSE)