# 🎨 Ark AgentPlan Seedream Skill 安装使用教程

> 豆包 Seedream AI 图片生成 Skill - **火山方舟 Agent Plan 专属版本**
>
> ✅ 文生图 + 连贯图 + 图生图 全 6 种场景支持
> ✅ 真正流式输出，生成一张返回一张
> ✅ 提示词智能优化，自动提升出图质量
> ✅ 自动按日期归档到桌面 + 完整 metadata 记录
> ✨ **Agent Plan 专属：统一 baseurl，复用 api_key，无需单独配置**

---

## 📋 前置要求

在开始之前，请确保你已经：

1. ✅ 开通 **火山方舟 Agent Plan**（生图模型已内置，无需单独开通）
2. ✅ 已在当前运行工具中配置 Agent Plan API Key（语言模型、生图、生视频共用同一个 Key）
3. ✅ 当前工具平台已经安装并正常运行
4. ✅ 飞书/其他渠道机器人已经配置好

**✨ 核心优势：**
- 🎯 **无需单独配置**：直接复用 Agent Plan 的全局 API Key
- 🔗 **统一地址**：语言模型、生图、生视频共用同一 baseurl
- 🚀 **真正的一体化体验**：安装即用，零配置

---

## 🚀 安装步骤（全程 1 分钟）

```bash
# 1. 进入 Skills 目录
cd ~/.agents/skills

# 2. 确认 Skill 已存在（本版本为 Agent Plan 专属）
ls byted-ark-seedream-skill/
# 应该看到：SKILL.md  README.md  INSTALL.md  VERSION  scripts/
```

---

## 🔑 配置 API Key - **真正开箱即用，无需单独配置！**

### ✅ 自动检测配置（推荐，无需任何操作）

**Skill 会自动从你当前平台的配置中读取 API Key：**

| 平台 | 自动检测位置 |
|------|-------------|
| **OpenClaw** | `models.providers.*.apiKey` |
| **Hermes** | `model.api_key` |
| **Claude Code** | `ANTHROPIC_AUTH_TOKEN` 环境变量 |

**✨ 只要你的 Agent Plan 已经配置好了，生图功能直接就能用，你不需要做任何额外配置！** 🎉

---

### 手动输入 Key（首次使用时）

如果还没配置 Agent Plan，直接在对话中发送你的 API Key 即可（以 ark- 开头）。

> 💡 **安全默认**：API Key 默认仅本次临时使用，不会自动保存到全局配置。
> 
> 如需保存为全局配置（下次直接使用），请明确说明：**「保存这个 API Key」**。
> 
> 保存后，语言模型、生图、生视频、Embedding 等所有 Agent Plan 能力将自动复用该配置。

---

### 手动配置环境变量（仅用于独立验证）

如果需要独立验证，可以设置环境变量（不推荐，自动检测更方便）：

```bash
# 环境变量配置（兜底用，一般不需要设置）
```

---

## ✅ 验证生效

### 1. 重启 Gateway 加载新 Skill

```bash
openclaw gateway restart
```

### 2. 命令行本地测试（可选）

```bash
cd ~/.agents/skills/byted-ark-seedream-skill
node scripts/generate.js --prompt "一只可爱的英短蓝猫趴在窗边晒太阳" --size 2K
```

看到图片成功保存到桌面，说明安装成功！

### 3. 对话测试

在飞书里说：

```
给我画一张赛博朋克风格的城市夜景
```

就能直接生成图片了！

---

## 🎯 5 个常用示例，复制即用

### 示例 1：基础文生图
```
画一张宫崎骏风格的夏日乡村，蓝天白云下的麦田和风车
```

### 示例 2：连贯组图
```
生成一组 4 张图，主题是同一棵樱花树的四季变迁，统一吉卜力画风
```

### 示例 3：单参考图生图
```
[上传一张人物头像]
参考这个人物的五官，把背景换成冰雪城堡
```

### 示例 4：多参考图融合
```
[上传图1：人物肖像] [上传图2：赛博朋克风格背景]
把图1的人物放到图2的背景中，保持人物特征不变
```

### 示例 5：指定参数
```
生成一只机械赛博风格的哈士奇，分辨率 3K，不要水印
```

---

## ⚙️ 完整参数说明

| 参数 | 默认值 | 说明 |
|------|-------|------|
| `--prompt` | 必填 | 图像描述 |
| `--size` | 2K | 分辨率按模型选择，见 MODELS.md |
| `--count` | 4 | 组图模式下生成的图片数量（1-15） |
| `--sequential` | false | 是否开启连贯组图模式 |
| `--stream` | 组图自动开启 | 是否开启流式输出 |
| `--watermark` | true | 是否添加水印 |
| `--optimize` | true | 是否自动优化提示词 |

---

## ❓ 常见问题 FAQ

### Q：图片保存在哪里？
A：默认在桌面的 `Seedream-Images` 文件夹，按日期子目录归档，同时生成完整的 metadata JSON 文件记录所有生成参数。

### Q：图生图支持本地图片吗？
A：支持两种输入格式：
- ✅ **HTTP URL**：必须公网可访问
- ✅ **Base64 编码**：格式 `data:image/png;base64,xxx`，适合 VPC/网络隔离环境

### Q：最多能传几张参考图？
A：Lite 最多14张，输入+输出≤15；Pro 普通生成最多10张，拆图层/透明编辑只能1张。

### Q：网络受限环境可以用吗？
A：可以！使用 base64 格式传参考图，完全不需要公网访问能力。

### Q：流式输出是什么意思？
A：生成一张就返回一张，不用等所有图片都生成完才看到第一张，大幅降低等待感知时间。

### Q：提示词优化是什么？
A：自动识别用户输入是单张还是连贯图场景，应用不同的提示词增强策略，大幅提升出图质量。

---

## 📦 包含的功能清单

| 功能 | 支持状态 |
|------|---------|
| 文生图 - 单张 | ✅ |
| 文生图 - 连贯组图（最多15张） | ✅ |
| 图生图 - 单参考→单张 | ✅ |
| 图生图 - 单参考→一组 | ✅ |
| 图生图 - 多参考→单张（最多14张） | ✅ |
| 图生图 - 多参考→一组 | ✅ |
| 真正流式输出（生成一张返回一张） | ✅ |
| 提示词智能优化（单张/连贯图差异化策略） | ✅ |
| 自动按日期归档到桌面 | ✅ |
| 完整 metadata JSON 记录 | ✅ |
| URL / Base64 双格式支持 | ✅ |
| 参考图融合 | Lite最多14张，Pro最多10张 |
| 下载失败容错处理 | ✅ |
| 参数边界检查 | ✅ |

---

**✅ 安装完成！现在可以开始尽情画图了！** 🎨