# @fmode/image

AI 图片生成器 —— 一行命令出架构图、产品界面、场景插图、整页 PPT。

纯 ESM、零依赖、Node 18+。

## 安装

```bash
npm install -g @fmode/image
```

或直接运行：

```bash
npx @fmode/image --app "后台管理界面" demo
```

## 配置

```bash
export FMODE_API_KEY="sk-..."   # 必需
```

也支持从 `~/.fmode/config.json` 读取：

```json
{ "api_key": "sk-..." }
```

## 快速开始

```bash
# 架构图
fmode-image --arch "四层技术架构：数据采集、模型服务、业务应用、终端" arch1

# 产品界面（表现力最强）
fmode-image --app "母婴营养管理后台，左侧导航，主区客户列表与健康曲线" dashboard

# 整页 PPT
fmode-image --slide "商业计划书封面，深蓝底，标题《未来飞马》" cover

# 场景插图
fmode-image --scene "深夜办公室，一个人对着三块屏幕" night-work
```

## 七种模式

| 模式 | 用途 | 尺寸 | 单价 |
|---|---|---|---|
| `--arch` | 架构/分层/闭环图 | 1792×1024 | ¥0.5 |
| `--app` | 产品界面（表现力最强） | 1792×1024 | ¥0.5 |
| `--slide` | 整页 PPT 直接使用 | 1920×1088 | ¥0.5 |
| `--explode` | 内部运转/拆解图 | 1792×1024 | ¥0.5 |
| `--product` | 产品设计图（硬件/工业） | 1792×1024 | ¥0.5 |
| `--scene` | 场景/人物/痛点插图 | 1024×1024 | ¥0.3 |
| `--detail` | 零件/材质/实物特写 | 1024×1024 | ¥0.3 |

## 代码调用

```javascript
import { gen, genApp, batch } from '@fmode/image';

// 单张
await genApp('营销数据看板，左侧导航，主区折线图', 'board');

// 指定模型
await gen('--slide', '产品发布会封面', 'cover', {
  model: 'gpt-image-2.5-sunburst',
  outdir: './out',
});

// 批量
await batch([
  ['--arch', 'arch1', '四层架构图'],
  ['--app', 'ui1', '管理后台'],
  ['--slide', 'cover', '项目封面'],
]);
```

## 模型

| 模型 | 特点 | 速度 |
|---|---|---|
| `gpt-image-2.6-sunburst` | **默认**。中文渲染质量最高，长文本与数据逻辑一致性最好 | 40-90s |
| `gpt-image-2.5-sunburst` | 稳定可用，中文渲染良好 | 40-60s |

**自动回退**：主模型不可用时，会自动尝试回退链中的下一个模型。凭据错误（401/403）不会触发回退。

```bash
# 查看可用模型
fmode-image --models

# 指定模型
fmode-image --app "界面" demo --model gpt-image-2.5-sunburst

# 通过环境变量
FMODE_IMAGE_MODEL=gpt-image-2.5-sunburst fmode-image --app "界面" demo
```

## 使用建议

### 什么场景用 AI 生图

- ✅ **架构图、流程图、闭环图** —— AI 出图比手画快得多，版式也更好看
- ✅ **产品界面概念图** —— 表现力最强，适合方案演示
- ✅ **整页 PPT 版式** —— 文字量适中的页面，一次成型
- ✅ **场景插图** —— 氛围感强的照片风格图

### 什么场景不要用

- ❌ **文字密集的页面** —— 表格、多列表、小字注释，AI 极易出现乱码、错字、数字错位
- ❌ **需要精确还原的实物** —— 产品特写、服装细节、证件照片
- ❌ **数据图表** —— AI 画不准真实数值，会编造数据

**推荐做法**：文字密集页用 HTML/CSS 精确排版，AI 只负责出背景和插图，两者合成。

### 出图后必须验证

AI 生成的图**一定要逐张检查**，重点看：

1. **中文是否准确** —— 有没有错字、乱码、生造词
2. **数字是否合理** —— 图表里的数据有没有被编造
3. **逻辑是否一致** —— 比如看板写着 12,846 人，分页是否对得上

## API

### `gen(mode, prompt, name, opts)`

生成一张图。

- `mode` — 模式，如 `--app`
- `prompt` — 提示词
- `name` — 输出文件名（不含扩展名）
- `opts.model` — 指定模型
- `opts.outdir` — 输出目录
- `opts.silent` — 静默模式

返回输出文件的绝对路径。

### `batch(tasks, opts)`

批量生成。`tasks` 是 `[mode, name, prompt]` 数组。

返回 `{ ok, fail, cost }`。

### `MODES` / `MODEL_INFO` / `DEFAULT_MODEL`

模式注册表、模型信息、默认模型。

## 环境变量

| 变量 | 说明 |
|---|---|
| `FMODE_API_KEY` | API 密钥（必需） |
| `FMODE_IMAGE_MODEL` | 默认模型 |
| `SKILL_IMAGE_OUTPUT` | 默认输出目录 |
| `FMODE_API_BASE` | API 地址（默认 `https://api.fmode.cn`） |
| `FMODE_IMAGE_VERBOSE` | 设置后输出模型回退的详细日志 |

## License

MIT
