小黑配图工作流 (Xiaohei Image Workflow)

一个基于固定 IP 形象的结构化图像生成工作流，提供 Web UI 和命令行两种使用方式。

功能特性

固定 IP 形象：使用"小黑"等预设 IP 角色生成一致风格的配图
结构化提示词：将复杂提示词拆解为主题、构图、元素、标注等可控字段
Web UI：友好的网页界面，支持单图和批量生成
命令行工具：适合自动化和批处理场景
API 覆盖：Web UI 支持为单次生成临时指定 API URL、Key 和模型
后端预设：前端输入简洁，复杂的生成逻辑由后端配置文件控制

快速开始

1. 克隆仓库

git clone https://github.com/1parado/xiaohei-workflow.git
cd xiaohei-workflow

2. 安装依赖

pip install -r requirements.txt

需要 Python 3.7 以上版本。依赖包括：

Flask：Web UI 服务器
requests：API 请求

3. 配置 API

复制模板配置文件：

copy config.template.json config.json

编辑 config.json，填写你的图像生成 API 信息：

{
  "base_url": "https://api.example.com/v1",
  "api_key": "sk-your-api-key-here",
  "model": "gpt-image-2",
  "timeout": 120,
  "image_quality": "hd",
  "default_size": "1792x1024",
  "prompt_mode": "ip_workflow",
  "default_ip": "xiaohei",
  "ip_workflow_preset": "presets/ip-workflow.json"
}

注意：config.json 包含敏感信息，已被 .gitignore 忽略，不会提交到版本库。

4. 启动 Web UI

python webui.py

或者使用 Windows 批处理脚本：

start.bat

打开浏览器访问：

http://localhost:5000

配置说明

`config.json` 字段说明

字段	说明	默认值
`base_url`	图像 API 的基础 URL	无
`api_key`	API 密钥	无
`model`	使用的模型名称	无
`timeout`	请求超时时间（秒）	`120`
`image_quality`	图像质量（`standard` / `hd`）	`hd`
`default_size`	默认图像尺寸	`1792x1024`
`prompt_mode`	提示词模式（`ip_workflow` / `raw`）	`ip_workflow`
`default_ip`	默认 IP 形象	`xiaohei`
`ip_workflow_preset`	IP 工作流预设文件路径	`presets/ip-workflow.json`

使用方式

Web UI 模式

启动 Web UI 后，你可以：

单张生成

API 信息（可选）：如果要覆盖 config.json 的设置，填写 API URL、API Key 和 Model
文件名：生成的图片文件名（不需要 .png 后缀）
IP 形象：选择预设的 IP 角色（如"小黑"）
提示词：用简短的中文描述你想要的配图内容

点击"生成图片"按钮开始生成。

批量生成

选择 IP 形象
在"批量提示词"文本框中，每行一个提示词
（可选）在"批量图片名称"中，每行一个文件名；留空的行会自动追加 -01、-02 等序号
设置并发数（同时生成的图片数量）
点击"批量生成"

后端工作流程

Web UI 的输入字段非常简洁，但背后的生成逻辑由 presets/ip-workflow.json 中的 backend_task 控制：

structure_type：结构类型（概念隐喻、流程工作流、前后对比等）
theme：主题
core_idea：核心意思
composition：画面构图和动作
elements：建议元素
labels：中文手写标注

PromptBuilder 会将前端输入的提示词与后端预设的字段合并，生成最终的完整提示词。

命令行交互模式

python workflow.py

按提示输入：

输出目录
图片数量
每张图的文件名、IP 形象、主题、构图、元素、标注等

适合需要精细控制每个字段的场景。

批量生成模式

创建批量配置文件（参考 examples/batch-config.json）：

{
  "output_dir": "./output",
  "tasks": [
    {
      "filename": "concept-01.png",
      "mode": "ip_workflow",
      "ip": "xiaohei",
      "structure_type": "concept-metaphor",
      "theme": "API 请求流程",
      "core_idea": "从客户端发起请求到服务器响应的完整流程",
      "composition": "小黑站在中央，左手发送请求信封，右手接收响应纸条",
      "elements": "请求信封, 网络线条, 响应纸条, 箭头",
      "labels": "请求, 处理, 响应"
    },
    {
      "filename": "workflow-02.png",
      "mode": "ip_workflow",
      "ip": "xiaohei",
      "structure_type": "workflow",
      "theme": "数据处理管道",
      "core_idea": "数据经过三个阶段的处理流程",
      "composition": "小黑在三个工作台之间移动，左侧输入原始数据，中间处理，右侧输出结果",
      "elements": "数据文件, 处理工具, 输出文档, 流程箭头",
      "labels": "输入, 转换, 输出"
    }
  ]
}

运行：

python workflow.py --batch examples/batch-config.json

Skill 调用

如果你使用 Claude Code 并将此项目配置为 Codex Skill，可以直接调用：

from workflow import load_config, create_generator

config = load_config()
generator = create_generator(config, "./output")

result = generator.generate_single({
    "filename": "skill-output.png",
    "mode": "ip_workflow",
    "ip": "xiaohei",
    "prompt": "一个简单的技术概念示意图"
})

print(result)

注意：使用 Skill 调用时，prompt 会与 backend_task 合并。如果不传入其他字段，完全由后端预设决定生成内容。

预设管理

IP 形象配置

编辑 presets/ip-workflow.json 的 ip_characters 字段：

"ip_characters": {
  "xiaohei": {
    "name": "小黑",
    "role": "默认视觉 IP，认真做荒诞事的系统操作员",
    "prompt": "小黑, a small solid-black absurd creature with white dot eyes, tiny thin legs, blank serious expression, slightly uneven hand-drawn body shape. 小黑 must perform the core conceptual action, not decorate the scene. Make 小黑 serious, deadpan, and slightly bizarre, not cute.",
    "avoid": [
      "不要过度可爱的吉祥物",
      "不要儿童卡通角色",
      "不要复杂服装、表情包、闪亮眼睛",
      "不要只是站在角落里看"
    ]
  }
}

你可以添加新的 IP 形象，或修改现有 IP 的提示词和约束。

后端任务配置

修改 backend_task 来改变 Web UI 默认生成的内容：

"backend_task": {
  "mode": "ip_workflow",
  "structure_type": "concept-metaphor",
  "theme": "你的默认主题",
  "core_idea": "核心概念说明",
  "composition": "画面构图描述，必须让 IP 角色执行核心动作",
  "elements": "元素1, 元素2, 元素3",
  "labels": "标注1, 标注2, 标注3"
}

原则：

一张图只解释一个核心概念
IP 角色必须是画面的核心操作者，不是装饰
标注要简短、稀疏（5-8 个）
保持视觉风格统一（纯白背景、手绘线条、少量色彩标注）

结构类型

预设支持多种结构类型：

concept-metaphor：概念隐喻
workflow：流程工作流
before-after：前后对比
system-slice：系统局部
role-state：角色状态
layered-method：方法分层
route-map：地图路线
mini-comic：小漫画分镜

在 structure_types 数组中添加或修改结构类型定义。

目录结构

xiaohei-workflow/
├── core/                       # 核心模块
│   ├── api_client.py          # API 客户端
│   ├── image_generator.py     # 图像生成器
│   └── prompt_builder.py      # 提示词构建器
├── presets/                    # 预设配置
│   └── ip-workflow.json       # IP 工作流预设
├── templates/                  # Web UI 模板
│   └── index.html             # 主页面
├── static/                     # 静态资源
│   ├── style.css              # 样式
│   └── script.js              # 前端脚本
├── examples/                   # 示例配置
│   └── batch-config.json      # 批量生成配置示例
├── agents/                     # Agent 定义（用于 Claude Code）
├── output/                     # 生成的图片输出目录
├── config.json                 # API 配置（不提交到版本库）
├── config.template.json        # 配置模板
├── webui.py                    # Web UI 入口
├── workflow.py                 # 命令行工具入口
├── requirements.txt            # Python 依赖
├── start.bat                   # Windows 启动脚本
└── README.md                   # 本文档

安全规则

配置文件安全

config.json 包含 API 密钥，已被 .gitignore 忽略
不要将 config.json 提交到版本库
不要在日志或响应中打印 API 密钥

Web UI 安全

Web UI 仅监听本地 127.0.0.1:5000，不对外网开放
如需远程访问，请使用反向代理并配置身份验证
API 覆盖功能仅在当前请求生效，不会修改 config.json

文件上传限制

Web UI 限制单次请求最大 16MB
批量生成时，建议单次不超过 50 张图片
并发数过高可能导致 API 限流

常见问题

Q: Web UI 启动后无法访问？

A: 检查端口 5000 是否被占用：

netstat -ano | findstr :5000

如果被占用，修改 webui.py 中的 app.run(port=5000) 为其他端口。

Q: 生成的图片不符合预期风格？

A: 检查以下几点：

presets/ip-workflow.json 的 style.visual_dna 和 constraints 是否正确
IP 角色的 avoid 规则是否足够明确
提示词是否与 backend_task 冲突

Q: 如何添加新的 IP 形象？

A: 在 presets/ip-workflow.json 的 ip_characters 中添加新条目，参考现有的"小黑"格式。

Q: 批量生成时部分图片失败？

A: 查看日志输出，通常是 API 超时或限流导致。可以：

降低并发数
增加 config.json 中的 timeout 值
检查 API 配额

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

GitHub: 1parado
仓库: xiaohei-workflow

感谢LinuxDo，学AI上L站

https://linux.do/

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
agents		agents
core		core
examples		examples
presets		presets
templates		templates
.gitignore		.gitignore
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SKETCH-UI.md		SKETCH-UI.md
SKILL.md		SKILL.md
SUMMARY.md		SUMMARY.md
config.template.json		config.template.json
requirements.txt		requirements.txt
start.bat		start.bat
webui.py		webui.py
workflow.py		workflow.py

Folders and files

Latest commit

History

Repository files navigation

小黑配图工作流 (Xiaohei Image Workflow)

目录

功能特性

快速开始

1. 克隆仓库

2. 安装依赖

3. 配置 API

4. 启动 Web UI

配置说明

config.json 字段说明

使用方式

Web UI 模式

单张生成

批量生成

后端工作流程

命令行交互模式

批量生成模式

Skill 调用

预设管理

IP 形象配置

后端任务配置

结构类型

目录结构

安全规则

配置文件安全

Web UI 安全

文件上传限制

常见问题

Q: Web UI 启动后无法访问？

Q: 生成的图片不符合预期风格？

Q: 如何添加新的 IP 形象？

Q: 批量生成时部分图片失败？

许可证

贡献

联系方式

感谢LinuxDo，学AI上L站

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`config.json` 字段说明

Packages