# Seedream 配置指南

本文档包含 Seedream Skill 的 API Key 检测策略、配置说明、技术实现细节。

---

## 🔑 API Key 检测策略（三层优先级）

Skill 会按照以下优先级自动检测 API Key，**99% 的用户不需要手动配置**。

---

### 🥇 优先级 1：用户在对话中直接发送（最高优先级）

用户直接在对话中发送以 `ark-` 开头的 API Key：

```
用户：ark-xxxxxxxxxxxx
```

**处理逻辑：**
1. ✅ 自动校验 Key 格式有效性（必须以 `ark-` 开头）
2. ✅ 默认仅本次临时使用，不自动写入配置文件
3. ✅ 如需保存为全局配置，请明确说「保存这个 API Key」，传入 `--save-api-key` 才写入
4. ✅ 写入前自动备份原配置文件（API Key 已脱敏）

仅临时使用的 Key 不会在后续进程中自动保留。

---

### 🥈 优先级 2：平台专属检测（根据当前运行平台读取对应配置）

Skill 先检测当前运行平台，然后从对应位置读取 API Key：

| 平台 | 检测方法 | 字段名 | 说明 |
|------|---------|--------|------|
| **OpenClaw** | 检测 `~/.openclaw/` 目录存在 | `models.providers.*.apiKey` | 遍历所有 provider，找第一个有效 Key |
| **Hermes** | 检测 `~/.hermes/` 目录存在 | `model.api_key` | YAML 配置文件中的字段 |
| **Claude Code** | 检测 `~/.claude/` 目录或环境变量存在 | `~/.claude/settings.json` 中的 `env.ANTHROPIC_AUTH_TOKEN`，或会话环境变量 `ANTHROPIC_AUTH_TOKEN` | 已有 token 时不自动覆盖 |

> ⚠️ **重要**：只读取对应平台的配置，不会跨平台读取其他工具的配置。

---

### 🥉 优先级 3：兜底兼容（通用环境变量扫描）

如果平台检测没有找到 Key，或者当前运行平台不是上面三个，会扫描 API Key**通用命名变体**（各平台常见的字段命名，避免误扫）：

```
ANTHROPIC_AUTH_TOKEN
API_KEY
API_Key
API_Keys
api_key
apiKey
```

---

### ❌ 都没找到：明确提示用户

以上三层都没找到的话，Skill 会明确提示用户：
> 直接在对话中发送以 `ark-` 开头的 API Key，默认仅本次临时使用；如需保存到全局配置，请明确确认

---

## 🔧 技术实现说明（高级用户）

### 提示词自动优化逻辑
默认开启，自动提升画质描述：
```javascript
// 自动添加的优化词：
"电影质感, 专业摄影, 8K分辨率, 极致细节, 光影层次, 色彩饱满"
```

用户说"不要优化"、"用原提示词"时自动关闭。

### 内置 10 大风格预设
自动从用户输入中识别风格关键词：
- 电影风、二次元、插画风、写实风、国潮风
- 赛博朋克、水彩风、3D渲染、暗黑风、治愈系

### 三级路径降级策略
| 优先级 | 路径 | 说明 |
|-------|------|------|
| 1 | `~/Desktop/Seedream-Images/` | 桌面环境优先 |
| 2 | `~/Seedream-Images/` | 无桌面环境时降级到主目录 |
| 3 | `./Seedream-Images/` | 最终兜底，当前运行目录 |

---

## 📋 常用模型速查表

| 模型 ID | 说明 |
|---------|------|
| `doubao-seedream-5.0-lite` | 普通生成默认；组图、联网、流式 |
| `doubao-seedream-5.0-pro` | 精准编辑、图层拆分、多语种单图 |

---

## 📋 高级配置（一般不需要）

如需使用独立账号或自定义配置，可以通过以下环境变量覆盖：

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `ARK_SEEDREAM_MODEL` | auto / lite / pro / AgentPlan 模型 ID；优先于 ARK_MODEL | `auto` |
| `ARK_SEEDREAM_API_BASE_URL` | 自定义 API 地址 | 官方地址 |
| `ARK_SEEDREAM_SAVE_PATH` | 图片保存路径 | 自动检测 |
| `ARK_API_BASE_URL` | 全局 API 地址（兜底） | - |
| `ARK_SAVE_PATH` | 全局保存路径（兜底） | - |

> 💡 API Key 通过三层自动检测策略获取，一般不需要通过环境变量配置。

`--model` 优先于模型环境变量；`--model auto` 可显式恢复自动选模。模型参数与兼容限制见 [MODELS.md](MODELS.md)。