Doubao Image Generator — AI 文生图工具 based on SeeDream 5.0

使用字节跳动豆包 Doubao SeeDream 模型生成高质量图片。支持文生图、AI 绘图、插画创作等功能。

Security Scan

The skill appears to implement a legitimate Doubao/SeeDream image generator, but its registry metadata and declarations are inconsistent with the shipped scripts (notably a required ARK_API_KEY is not declared), and some runtime behaviors (printing system info, revealing partial API key, downloading arbitrary image URLs) warrant caution before installing.

Purpose & Capability

The name/description (Doubao SeeDream image generation) align with the provided code and runtime instructions: the Bash and Python scripts call a Volcengine/ARK API endpoint to generate and download images. However the registry metadata incorrectly lists no required environment variables and no install spec despite the package requiring an ARK_API_KEY and including runnable scripts — that metadata mismatch is an incoherence that should be resolved.

Instruction Scope

SKILL.md and the scripts confine behavior to: checking environment, calling POST https://ark.cn-beijing.volces.com/api/v3/images/generations with the ARK_API_KEY, parsing the JSON result, and downloading the returned image URL(s) to disk. The environment-check script prints system info (whoami, pwd, hostname) and displays the first 10 characters of ARK_API_KEY for verification; the scripts also perform ping/curl checks. They do not appear to access unrelated credentials or arbitrary local config paths. Two caution points: (1) printing partial API key and system details may leak sensitive local info to whoever runs the script output, and (2) downloaded image URLs come from API responses and may point to arbitrary hosts (the script will fetch them), so be mindful that network fetches could follow redirects or access external servers.

Install Mechanism

There is no remote installer or download URL; the repository provides local Bash and Python scripts and documentation. No installation step pulls arbitrary remote archives or executes unsigned code from external servers. Because the skill is 'instruction-only' in the registry but includes code files, the primary risk is running those local scripts — no high-risk installer was observed.

Credentials

The scripts legitimately require one secret: ARK_API_KEY (firewall/API key for Volcengine/ARK). That credential is proportional to the skill's purpose. However the skill metadata in the registry lists no required env vars or primary credential, which is inconsistent and could mislead users/automated reviewers. Additionally, the environment-check script prints the first 10 characters of the API key and exposes local system information (user, hostname, working directory) to stdout — this is not necessary for functionality and increases information exposure.

Persistence & Privilege

The skill does not request always:true or any platform-wide privileges. It writes generated images to a local output directory (configurable) and does not modify other skills or global agent settings. File writes are limited to the output directory. No evidence that the skill attempts to persist credentials or change system-wide config.

What to consider before installing

Key things to consider before installing/running: 1) Metadata mismatch: the registry claims no required env vars, but the scripts require ARK_API_KEY — confirm the skill author/source and insist the package metadata be corrected to declare ARK_API_KEY as required. Don't rely solely on registry fields. 2) Inspect before running: you should review the shipped scripts locally (they are included) and confirm the API endpoint (ark.cn-beijing.volces.com) and model name match what you expect. The code is readable; if you can't inspect, avoid running. 3) Limit information exposure: the environment check prints current user, hostname, working dir, and the first 10 characters of ARK_API_KEY. That is convenient for debugging but leaks local info to whoever can see the terminal. Run the scripts in a trusted, isolated environment (or remove those printouts) if you are concerned. 4) Network fetch risk: the skill will download image URLs returned by the API — those URLs may point to external hosts and will be fetched without additional validation. If you must run it, consider running in a network-restricted environment or auditing the returned URLs before automatic downloading. 5) Secrets handling: supply ARK_API_KEY only to trusted code. Prefer setting the env var in a session (not checked into files) and verify there are no hard-coded keys (the package asserts none). 6) Source provenance: the skill lists 'Source: unknown' and placeholder GitHub links. Favor installing only from known/trusted sources or official repositories. Ask the publisher to provide a real homepage/repo and fix metadata inconsistencies. If you want, I can point out the exact lines in the scripts that print system info or the API key preview and suggest precise edits to harden them (e.g., remove whoami/pwd prints, stop displaying any part of the API key, add URL validation before downloading).

豆包文生图（Doubao SeeDream）Skill

基于字节跳动火山引擎 ARK API，调用豆包 SeeDream 5.0 模型进行 AI 文生图创作。

📋 目录

• 功能特性
• 前置条件
• 安装方式
• 使用方法
• API 参数详解
• 触发条件
• 工作流
• 错误处理
• 最佳实践
• 常见问题
• 技术实现
• 版本历史

✨ 功能特性

• 🎨 高质量图像生成 - 基于豆包 SeeDream 5.0 模型，支持 2K/1080P/720P 分辨率
• 🔧 灵活参数配置 - 支持尺寸、水印、格式等多种参数自定义
• 📦 双脚本实现 - 提供 Bash 和 Python 两种实现方式，适应不同环境
• 🛡️ 完善的错误处理 - 详细的错误提示和日志记录
• 💾 自动保存管理 - 智能图片下载和本地保存
• 🚀 快速响应 - 优化的 API 调用流程，减少等待时间

🔐 前置条件

环境变量配置

必须设置火山引擎 ARK API Key：

export ARK_API_KEY="your_ark_api_key"

获取 API Key 步骤：

1. 访问 火山引擎控制台
2. 登录/注册账号
3. 进入「应用管理」→「创建应用」
4. 选择「图像生成」服务
5. 复制生成的 API Key

系统依赖

Bash 脚本依赖：

• Bash 4.0+
• curl 7.0+
• Python 3.6+（用于 JSON 处理）

Python 脚本依赖：

• Python 3.8+
• requests 库（可选，已内置 fallback 方案）

环境检查脚本

#!/bin/bash
# 检查运行环境
check_environment() {
  local errors=0
  
  # 检查 ARK_API_KEY
  if [ -z "$ARK_API_KEY" ]; then
    echo "❌ 错误：缺少 ARK_API_KEY 环境变量"
    echo "   请执行：export ARK_API_KEY=your_key"
    errors=$((errors + 1))
  else
    echo "✅ ARK_API_KEY 已配置"
  fi
  
  # 检查 curl
  if ! command -v curl &> /dev/null; then
    echo "❌ 错误：缺少 curl 命令"
    errors=$((errors + 1))
  else
    echo "✅ curl 已安装 ($(curl --version | head -n1))"
  fi
  
  # 检查 Python
  if ! command -v python3 &> /dev/null; then
    echo "❌ 错误：缺少 Python 3"
    errors=$((errors + 1))
  else
    echo "✅ Python 已安装 ($(python3 --version))"
  fi
  
  return $errors
}

check_environment

📦 安装方式

方式一：通过 Clawhub 安装（推荐）

# 在 WorkBuddy 中执行
skill install doubao-image

方式二：手动安装

# 1. 克隆或下载技能到本地
git clone https://github.com/your-username/doubao-image-skill.git ~/.workbuddy/skills/doubao-image

# 2. 设置执行权限
chmod +x ~/.workbuddy/skills/doubao-image/scripts/*.sh

# 3. 配置环境变量
echo 'export ARK_API_KEY="your_key"' >> ~/.bashrc
source ~/.bashrc

方式三：直接复制

将 doubao-image 文件夹复制到 ~/.workbuddy/skills/ 目录即可。

🚀 使用方法

基础用法

# 使用默认参数生成图片
./scripts/doubao-image-generate.sh "一只在月光下的白色小猫"

# 指定分辨率（2K/1080P/720P）
./scripts/doubao-image-generate.sh "赛博朋克风格的城市夜景" "1080P"

# 关闭水印
./scripts/doubao-image-generate.sh "山水画" "2K" "false"

Python 脚本用法

# 基础用法
python3 scripts/doubao-image-generate.py \
  --prompt "一只在月光下的白色小猫"

# 完整参数
python3 scripts/doubao-image-generate.py \
  --prompt "赛博朋克风格的城市夜景" \
  --size "1080P" \
  --watermark false \
  --output-dir "./my-images" \
  --verbose

在 WorkBuddy 中使用

当用户说以下话语时自动触发：

• "生成一张...的图片"
• "帮我画一个..."
• "AI 绘图：..."
• "文生图..."

📊 API 参数详解

核心参数

参数名	类型	必填	默认值	说明
prompt	string	✅ 是	-	图片描述文本，支持中英文
model	string	❌ 否	doubao-seedream-5-0-260128	固定使用 SeeDream 5.0
size	string	❌ 否	2K	输出分辨率
watermark	boolean	❌ 否	true	是否添加水印
response_format	string	❌ 否	url	返回格式（url/base64）
stream	boolean	❌ 否	false	是否流式输出

尺寸参数说明

值	分辨率	适用场景
2K	2048×2048	高质量输出、印刷用途
1080P	1920×1080	社交媒体、网页展示
720P	1280×720	快速预览、移动端

高级参数（通过环境变量配置）

环境变量	说明	默认值
DOUBAO_API_TIMEOUT	API 超时时间（秒）	60
DOUBAO_RETRY_COUNT	失败重试次数	3
DOUBAO_OUTPUT_DIR	默认输出目录	generated-images

🎯 触发条件

主要触发词

生成图片、生成图像、创建图片
AI 绘图、文生图、画一张
帮我画、画一个、生成一张...的图
doubao image、豆包生图

触发示例

用户：帮我画一只可爱的猫咪
用户：生成一张赛博朋克风格的城市夜景图
用户：AI 绘图：夕阳下的海滩
用户：文生图 - 中国风山水画

🔄 工作流

1. 需求解析

用户输入 → 提取 prompt → 解析参数 → 验证完整性

解析逻辑：

• 提取引号内或冒号后的描述文本作为 prompt
• 识别尺寸关键词（2K/1080P/720P）
• 检测水印相关表述（"不要水印"/"去水印"）

2. 参数验证

验证流程：
├─ 检查 ARK_API_KEY 是否存在
├─ 检查 prompt 是否非空
├─ 验证 size 参数合法性
├─ 检查网络连接状态
└─ 准备 API 调用

3. API 调用

curl -X POST "https://ark.cn-beijing.volces.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "用户描述",
    "size": "2K",
    "watermark": true,
    "response_format": "url",
    "stream": false,
    "sequential_image_generation": "disabled"
  }'

4. 响应处理

成功响应：

{
  "data": [{
    "url": "https://example.com/image.png",
    "content": "base64_encoded_string"
  }],
  "usage": {
    "prompt_tokens": 50,
    "total_tokens": 50
  }
}

处理流程：

1. 解析 JSON 响应
2. 提取图片 URL
3. 下载图片到本地
4. 生成唯一文件名（带时间戳）
5. 通过 open_result_view 展示

5. 图片保存

# 保存路径规则
generated-images/
├── doubao-20260409-233045-abc123.png
├── doubao-20260409-233122-def456.png
└── ...

文件名格式： doubao-YYYYMMDD-HHMMSS-random.png

⚠️ 错误处理

错误码对照表

错误类型	HTTP 状态码	处理方式
未授权	401	提示检查 API Key
余额不足	402	提示充值
请求超限	429	自动重试（指数退避）
服务器错误	500/503	重试 3 次后报错
超时	504	延长超时时间重试
内容违规	400	提示修改 prompt

错误处理脚本

handle_error() {
  local status_code=$1
  local error_msg=$2
  
  case $status_code in
    401)
      echo "❌ 认证失败：API Key 无效或已过期"
      echo "   请重新获取：https://console.volcengine.com/ark"
      ;;
    402)
      echo "❌ 账户余额不足，请充值后重试"
      ;;
    429)
      echo "⚠️  请求频率超限，等待 ${retry_after}秒后重试..."
      sleep $retry_after
      ;;
    500|503)
      echo "⚠️  服务器繁忙，正在重试（第 $retry_count 次）..."
      ;;
    400)
      echo "❌ 请求被拒绝：${error_msg}"
      echo "   可能包含敏感词汇，请修改描述后重试"
      ;;
    *)
      echo "❌ 未知错误：${error_msg}"
      ;;
  esac
}

🎨 最佳实践

Prompt 编写技巧

优质 Prompt 公式：

主体描述 + 环境氛围 + 艺术风格 + 技术参数

示例：

✅ 好的 Prompt：
"一只白色波斯猫，坐在古老的图书馆窗台上，
午后阳光透过彩色玻璃，写实风格，4K 超精细细节，
景深效果，温暖色调"

❌ 差的 Prompt：
"一只猫"

风格关键词库

【艺术风格】
写实、油画、水彩、素描、动漫、赛博朋克、蒸汽朋克、
极简、抽象、印象派、超现实主义

【画面质量】
4K、8K、超高清、电影大片、精致细节、杰作

【光影效果】
光线追踪、全局光照、体积光、丁达尔效应、黄金时刻

【构图方式】
对称构图、三分法、引导线、框架构图、鸟瞰视角

性能优化

1. 批量生成：避免并发请求，串行处理更稳定
2. 缓存策略：相同 prompt 可复用历史结果
3. 超时设置：建议设置 60 秒超时
4. 重试机制：指数退避重试（1s, 2s, 4s, 8s）

❓ 常见问题

Q1: 生成的图片质量不佳？

解决方案：

• 使用更详细的 prompt 描述
• 添加质量关键词（4K、超精细、杰作）
• 选择 2K 分辨率
• 指定具体艺术风格

Q2: API 调用失败？

排查步骤：

1. 检查 ARK_API_KEY 是否正确
2. 验证网络连接
3. 查看账户余额
4. 检查是否触发频率限制

Q3: 图片下载失败？

解决方案：

# 手动下载
curl -L "图片 URL" -o "output.png"

# 检查输出目录权限
chmod 755 generated-images/

Q4: 如何批量生成？

脚本示例：

#!/bin/bash
prompts=(
  "春日樱花"
  "夏日海滩"
  "秋日枫叶"
  "冬日雪景"
)

for prompt in "${prompts[@]}"; do
  ./scripts/doubao-image-generate.sh "$prompt"
  sleep 2  # 避免频率限制
done

🛠️ 技术实现

目录结构

doubao-image/
├── SKILL.md                 # Skill 定义文件
├── README.md                # 详细文档
├── CHANGELOG.md             # 版本历史
├── LICENSE                  # 开源协议
├── scripts/
│   ├── doubao-image-generate.sh    # Bash 实现
│   ├── doubao-image-generate.py    # Python 实现
│   └── check-env.sh                # 环境检查
├── examples/
│   └── prompts.md                  # Prompt 示例
└── tests/
    └── test-api.sh                 # API 测试

核心代码流程

┌─────────────┐
│  用户输入   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  解析参数   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  验证环境   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  构建请求   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  调用 API   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  处理响应   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  下载图片   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  展示结果   │
└─────────────┘

安全考虑

1. API Key 保护：仅从环境变量读取，不硬编码
2. 输入验证：严格过滤 prompt 内容
3. 错误隔离：异常不会泄露敏感信息
4. 权限控制：脚本执行权限限制

📝 版本历史

v2.0.0 (2026-04-09) - Clawhub 发布版

• ✨ 重构代码结构，符合 Clawhub 标准
• ✨ 新增 Python 实现版本
• ✨ 完善错误处理和日志记录
• ✨ 添加详细使用文档
• 🐛 修复 JSON 转义问题
• 🐛 优化超时重试机制

v1.0.0 (2026-01-15) - 初始版本

• ✨ 基础 Bash 脚本实现
• ✨ 支持基本文生图功能
• ✨ 简单的错误处理

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

• 火山引擎 ARK 文档
• 豆包 SeeDream 介绍
• Clawhub 技能开发指南
• GitHub 仓库

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

# Fork 项目
# 创建功能分支
git checkout -b feature/your-feature

# 提交更改
git commit -m "feat: add your feature"

# 推送到分支
git push origin feature/your-feature

# 创建 Pull Request

📧 联系方式

• 作者：YangYang
• Email: [e-mail]
• 问题反馈：GitHub Issues

---

最后更新： 2026-04-09
当前版本： 2.0.0
维护状态： 活跃维护中