# Sensenova Infographic

> 用商汤 SenseNova U1 Fast（sensenova-u1-fast）生成中文信息图 / 海报 / 知识卡片。 该模型是专精信息图的原生图像生成模型，文字渲染达商业级精度、排版规整。 内置针对中文场景优化的结构化提示词模板库（对比图/流程图/数据图/知识卡片/清单/海报）。 Use when the user wants to make an infographic, poster, knowledge card, data visualization image, or 信息图 with SenseNova / 商汤 / U1. 触发词：信息图, 生成信息图, 商汤信息图, SenseNova, sensenova-u1-fast, U1, 海报, 知识卡片, 数据可视化图, infographic, 科普图, 流程图海报, 清单图。

- Skill: `chenoneto/sensenova-infographic` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add chenoneto/sensenova-infographic`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chenoneto/sensenova-infographic/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: chenoneto (https://skillmd.com/u/chenoneto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chenoneto/sensenova-infographic

---


# SenseNova U1 Fast — 中文信息图生成

## Overview

`sensenova-u1-fast` 是商汤 SenseNova U1（NEO-Unify 理解生成统一架构）的加速版，**专精信息图**：
文字渲染达商业级精度、能精准控制多栏边界、排版规整。本 skill 把「用户内容 → 结构化中文
Prompt → 调 API 生图 → 下载保存」串成稳定流程，并内置一套**中文优化提示词模板库**。

- 接口：`POST https://token.sensenova.cn/v1/images/generations`（OpenAI images 兼容）
- 模型：`sensenova-u1-fast`（固定）｜ Prompt 上限 **4096 tokens** ｜ 11 种固定分辨率
- 生图脚本：`scripts/generate_infographic.py`（纯标准库，零依赖，自动下载+重试）
- 提示词模板：`references/prompt-guide.md` ｜ 接口细节：`references/api.md`

> ⚠️ **U1 Fast 不是万能模型**：它只擅长**信息图/海报/排版类图像生成**。不要用它做：
> - 通用写实照片（人物/风景）
> - 图像理解/识图/问答
> - 纯艺术创作（它会被强制结构化，反而受约束）
> 对话/识图请走 `/v1/chat/completions` + `sensenova-6.7-flash-lite`。


---

## Prerequisites

🔴 **CHECKPOINT — 生图前必须确认 API Key，否则调用必失败：**

1. 访问 https://platform.sensenova.cn/console → API Keys，创建 sk- 开头的密钥（公测免费）。
2. 设置环境变量（**每次调用脚本都必须带**，Windows 还要带 UTF-8）：
   - Windows(bash)：`export SENSENOVA_API_KEY=sk-xxx`
   - 或调用脚本时用 `--api-key sk-xxx` 传入
3. **确认 Key 就绪后再进入下面的流程。** 未就绪 → 停下，先引导用户去控制台创建。

⚠️ API Key 是敏感凭据：**绝不硬编码进代码或提交到仓库**，只走环境变量 / `--api-key`。

---

## Workflow（5 步，逐步执行）

### Step 1 · 明确需求（输入 → 输出）
问清并锁定 4 件事，缺则用合理默认并**明确告知用户**：
- **主题内容**：要表达什么？把关键文字/数据尽量拿全（U1 渲染的就是你给的字）。
- **信息图类型**：对比 / 流程 / 数据 / 知识卡片 / 清单 / 海报（决定套哪个模板）。
- **风格**：扁平商务 / 可爱卡通 / 国风 / 科技 / 手账 / 波普 / 数据仪表（见 prompt-guide 风格库）。
- **尺寸**：默认横版 `2752x1536`；竖屏 `1536x2752`；小红书 `1824x2272`（见 api.md 尺寸表）。

### Step 2 · 选模板（读 prompt-guide.md）
按类型从 `references/prompt-guide.md` 的模板库选一个骨架（A 对比 / B 流程 / C 数据 / D 知识卡片 / E 清单 / F 海报）。**必须实际读取该文件**，不要凭记忆。

### Step 3 · 组装结构化中文 Prompt（核心，决定成败）
按黄金 5 段填满模板：【整体风格】【配色方案】【整体布局】【标题区】【各区块内容+底部】。
遵守五条铁律：① 文字写原文 ② 图标描述造型 ③ 布局用几何词 ④ 配色先定死 ⑤ 加防溢出约束。
Prompt 尽量写详细（上限 4096 tokens，用满更稳）。把最终 Prompt 存成 UTF-8 文件，例如
`<工作目录>/_sensenova_prompt.txt`，避免命令行超长/转义问题。

🔴 **CHECKPOINT**：把组装好的 Prompt 先展示给用户确认（尤其文字/数据/配色），确认后再生图。

### Step 4 · 调用脚本生图

```bash
# 基础调用
PYTHONIOENCODING=utf-8 python "C:/Users/MSI/.workbuddy/skills/sensenova-infographic/scripts/generate_infographic.py" \
  --prompt-file "<工作目录>/_sensenova_prompt.txt" \
  --size 2752x1536 \
  --output "<工作目录>/信息图_主题.png"

# 按宽高比快速选尺寸（16:9 / 9:16 / 1:1 / 4:5 ...）
PYTHONIOENCODING=utf-8 python scripts/generate_infographic.py \
  --prompt-file prompt.txt --aspect-ratio 16:9 --output out.png

# 干运行：不烧 Token，先校验 Prompt / 请求体
PYTHONIOENCODING=utf-8 python scripts/generate_infographic.py \
  --prompt-file prompt.txt --dry-run --show-prompt

# JSON 输出，方便自动化流程解析
PYTHONIOENCODING=utf-8 python scripts/generate_infographic.py \
  --prompt-file prompt.txt --json --output out.png
```

- 脚本自动：校验 size 白名单 → Prompt 静态检查（HEX 色值、token 超限、结构缺失） → 调 API（401/400 不重试，429/5xx/超时退避重试 3 次） → 下载签名 URL 保存。
- 多张时（`--n>1`）自动加序号。成功后：默认输出 `SAVED_FILES=[...]`；`--json` 模式输出完整 JSON 结果。


### Step 5 · 展示结果
用 present_files 展示保存的 PNG。若用户要微调，回 Step 3 改 Prompt 局部再生成（不要从头重写）。

---

## 内置提示词模板速查（详见 references/prompt-guide.md）

| 模板 | 用途 | 默认尺寸 |
|------|------|---------|
| A 三栏对比/并列要点 | 优缺点、方案对比、三大功能 | 2752x1536 |
| B 流程步骤图 | 操作步骤、工作流、时间线 | 2752x1536 / 竖版 |
| C 数据可视化 | 报告、统计、KPI 大数字 | 2752x1536 / 2496x1664 |
| D 知识卡片/九宫格 | 科普、教程、小红书 | 1536x2752 / 2048x2048 |
| E 清单 Checklist | 待办、要点、攻略 | 1536x2752 / 1344x3136 |
| F 单页海报/封面 | 活动、公告、封面 | 1664x2496 / 1536x2752 |

**黄金结构**（任何图都套）：【整体风格】+【配色方案】+【整体布局】+【标题区】+【各区块精确文字与图标】+【底部】。

---

## 失败模式与回退（if-then）

### 阶段一 · 生图前检查
| 检查项 | 失败 → 处理 |
|--------|-----------|
| API Key 是否就绪 | → **立即停止**，引导去 https://platform.sensenova.cn/console 创建 |
| size 是否在 11 白名单内 | → 脚本直接报错并列出白名单；换合法值；或用 `--aspect-ratio` 映射 |
| Prompt 是否 ≤4096 tokens | → 脚本打印约算 token 警告；精简文字或拆两张图 |
| Prompt 是否结构化 | → 若是"意识流"一句话，先按黄金 5 段重写再生图 |
| 脚本静态检查是否有警告（HEX色值/缺结构/缺约束） | → 按提示修复后再生图；可用 `--dry-run` 先不烧 Token 校验 |

### 阶段二 · API 调用失败
| 错误 | 含义 | 一线修复 | 仍失败 → 兜底 |
|------|------|---------|-------------|
| **401/403** | Key 无效/无权限 | 去控制台确认 Key 有效、未注销 | 让用户重建 Key；不自动重试 |
| **400** | 参数错误 | 检查 model=`sensenova-u1-fast`、size 白名单 | 回退最小参数（model+prompt+默认 size）重试 |
| **404** | 接口用错 | 确认走 `/v1/images/generations` 而非 chat | 核对 Base URL 子域名是 `token.sensenova.cn` |
| **429** | 频率超限（1500次/5h） | 等待 Retry-After | 退避 5→15→30s 重试，最多 3 次 |
| **5xx/超时** | 服务端/网络 | 退避重试 | 3 次失败告知用户稍后再试 |
| **URL 下载失败** | 签名 URL 过期(>1h) | 立即重跑生图拿新 URL | 脚本会打印原始 URL 供手动下载 |

### 阶段三 · 出图质量不达标（实测高频）
| 症状 | 修复（改 Prompt 后重生） |
|------|------------------------|
| 文字模糊/错字 | 加「标题粗体、小字边缘锐利」+ 简化背景；文字过多则拆图 |
| 布局混乱 | 换几何布局词 + 强调"区块外观完全统一"；区块数降到 ≤4 |
| 内容溢出边框 | 加「元素与边框保持安全间距，严禁溢出」；缩短单块文字 |
| 配色杂乱 | 先定死主/辅/背景/文字四色；必要时降到双色 |

---

## 反例黑名单（不要做的事）

| # | 禁止行为 | 为什么 | 正确做法 |
|---|---------|--------|---------|
| 1 | **硬编码 API Key 到代码/仓库** | 泄露凭据 | 只用 `$SENSENOVA_API_KEY` 或 `--api-key` |
| 2 | **写"意识流" Prompt**（如"画个好看的海报字大点"）| U1 会跑偏、抽卡 | 按黄金 5 段结构化，文字写原文 |
| 3 | **只说"配几个图标"不描述造型** | 图标随机、不符主题 | 明确图标位置/造型/颜色 |
| 4 | **传非白名单分辨率**（如 `1920x1080`）| 直接 400 | 只用 11 种官方尺寸 |
| 5 | **用生图接口去做问答/识图** | 404 | 对话/识图走 `/v1/chat/completions` + `sensenova-6.7-flash-lite` |
| 6 | **Prompt 里只写"介绍三点"不给原文** | 模型自己编字，不可控 | 把三点的完整文字逐字写进 Prompt |
| 7 | **一次塞太多区块（>4-5块）+ 海量文字** | 排版必乱、文字糊 | 精简或拆成多张图 |
| 8 | **Windows 下不设 UTF-8 就跑脚本** | 中文/emoji 可能 GBK 报错 | 命令前加 `PYTHONIOENCODING=utf-8` |
| 9 | **签名 URL 拿到手不及时下载** | URL 约 1 小时失效 | 立即下载保存（脚本已自动做） |

---

## Runtime 适配性声明

本 skill 遵循 Agent Skills Standard，可在 Claude Code、Codex、Cursor、WorkBuddy、Hermes、
OpenClaw、Gemini CLI 等任何 skills-compatible runtime 运行。生图通过标准 HTTP（Python 标准库）
执行，无 runtime 特定依赖；脚本路径按各 runtime 的 skills 目录自行替换即可。

---

## 资源速查

| 路径 | 用途 |
|------|------|
| `scripts/generate_infographic.py` | 生图脚本：校验/调用/重试/下载，零依赖 |
| `references/prompt-guide.md` | 中文提示词工程指南 + 6 套模板库 + 风格库 |
| `references/api.md` | 接口规格 + 11 种分辨率 + 错误码 |

## 版本记录

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.1 | 2026-07-20 | 脚本增强：支持 `--aspect-ratio`、`--dry-run`、`--show-prompt`、`--json`；新增 Prompt 静态检查（HEX色值/token/结构/约束）；prompt-guide 补充配色写法指南与完整示例；SKILL.md 补充 U1 不适用场景 |
| 1.0 | 2026-07-17 | 初始版本：U1 Fast 信息图生成 + 中文优化提示词模板库 + 失败模式/黑名单/检查点 |