目录
1. 技能概述
技能是 AI 创意工坊的核心单元。每个技能定义了一个创作场景,包含:
- 元数据:名称、分类、图标、描述等展示信息
- 输入表单:用户需要填写的参数(自动生成 UI)
- 输出类型:text / image / video / voice(决定结果渲染方式)
- 执行流程:Agent 读取并遵循的指令(调用哪些工具、如何组合)
核心理念:添加新技能只需创建一个 SKILL.md 文件, 前端会自动生成对应的表单和结果展示,无需修改任何前端代码。
2. 文件结构
每个技能是 backend/skills/ 下的一个目录:
backend/skills/
├── avatar/ # 技能目录名 = 技能 ID
│ ├── SKILL.md # 必需:技能定义文件
│ └── examples.json # 可选:示例数据
├── greeting-card/
│ ├── SKILL.md
│ └── examples.json
└── your-new-skill/ # 新技能
├── SKILL.md
└── examples.json• 目录名:即技能的唯一标识(name),使用小写字母和连字符
• SKILL.md:YAML frontmatter + Markdown 正文
• examples.json:首页精选示例展示的数据
3. Frontmatter 字段
SKILL.md 文件以 YAML frontmatter 开头,定义技能的元数据:
---
name: greeting-card # 技能 ID(与目录名一致)
category: image # 分类:text / voice / image / video
display_name: 新年贺卡 # 展示名称
description: > # 技能描述(支持多行)
生成新年贺卡图片。支持多种风格和自定义文字内容。
icon: image # 图标名称(Lucide 图标)
chain_to: # 可联动的下游技能
- blessing-voice
- greeting-video
supports_upload: true # 是否支持上传图片
output_type: image # 输出类型(决定前端渲染器)
inputs: # 输入表单定义(详见下节)
- key: style
label: 风格
type: style_tags
# ...
---字段说明
| 字段 | 必需 | 说明 |
|---|---|---|
| name | 是 | 技能唯一标识,与目录名一致 |
| category | 是 | 分类:text / voice / image / video |
| display_name | 是 | 展示给用户的名称 |
| description | 是 | 技能描述,支持多行 |
| icon | 是 | Lucide 图标名:scroll / image / video / mic / user / gift / clock 等 |
| output_type | 是 | 输出类型:text / image / video / voice |
| inputs | 是 | 输入表单定义数组 |
| chain_to | 否 | 可联动的下游技能 ID 列表 |
| supports_upload | 否 | 是否支持图片上传,默认 false |
4. 输入类型详解
text文本输入
单行文本输入框
- key: keywords
label: 关键词
type: text
placeholder: "如:马年大吉、阖家欢乐..."
required: trueselect下拉选择
下拉选择框,适合选项较多的场景
- key: style
label: 风格
type: select
default: "传统"
options:
- { value: "传统", label: "传统" }
- { value: "幽默", label: "幽默" }
- { value: "文艺", label: "文艺" }style_tags标签选择
横向标签按钮组,适合选项较少的场景(推荐 2-6 个)
- key: aspect_ratio
label: 画面比例
type: style_tags
default: "auto"
options:
- { value: "auto", label: "自动" }
- { value: "1:1", label: "1:1" }
- { value: "16:9", label: "16:9" }
- { value: "9:16", label: "9:16" }image_upload图片上传
图片上传组件,返回 base64 data URL
- key: reference_image
label: 参考图片(可选)
type: image_upload
description: "上传图片后 AI 会参考其风格"slider滑块
数值滑块,适合时长、强度等参数
- key: duration
label: 时长
type: slider
default: 5
min: 2
max: 12
step: 1number数字输入
数字输入框,支持最小/最大值限制
- key: count
label: 数量
type: number
default: 3
min: 1
max: 10voice_picker语音选择
语音类型选择卡片(用于 TTS 技能)
- key: voice_type
label: 音色
type: voice_picker5. 可用工具
read_file读取文件内容(Agent 自动调用读取 SKILL.md)
参数:
path (string) - 文件路径返回:文件内容字符串
doubao_generate_text调用豆包大模型生成文本(春联、祝福语、签文等)
参数:
system_prompt (string) - 系统提示词user_message (string) - 用户消息返回:生成的文本内容
doubao_analyze_image调用豆包多模态模型分析图片
参数:
image_base64 (string) - 图片 base64 或 cached:KEYprompt (string) - 分析提示词返回:图片分析描述文本
seedream_text_to_image文生图 - 根据提示词生成图片
参数:
prompt (string) - 图片描述提示词aspect_ratio (string?) - 可选,如 1:1 / 16:9 / 9:16,不传则自动返回:cached:KEY(图片缓存引用)
seedream_image_to_image图生图 - 基于参考图生成新图片
参数:
prompt (string) - 图片描述提示词reference_image (string) - 参考图 base64 或 cached:KEYstrength (number) - 变化强度 0-1(0.3 大变化,0.7 小变化)aspect_ratio (string?) - 可选,画面比例返回:cached:KEY(图片缓存引用)
seedance_image_to_video图生视频 - 将首帧图片转为动态视频
参数:
first_frame (string) - 首帧图片 base64 或 cached:KEYduration (number) - 时长(秒)aspect_ratio (string?) - 可选,画面比例返回:视频 URL
tts_synthesize文字转语音
参数:
text (string) - 要朗读的文本voice_type (string) - 音色 IDspeed_ratio (number) - 语速 0.5-2.0volume_ratio (number) - 音量 0.5-2.0pitch_ratio (number) - 音调 0.5-2.0返回:{"audio_base64": "...", "duration": 5.2}
图片缓存机制
所有图片工具返回 cached:KEY 而非完整 base64, 避免大图片数据污染 LLM 对话上下文导致 Token 溢出。 在工具间传递图片时直接使用 cached:KEY 格式。
6. 执行流程编写
SKILL.md 的 Markdown 正文是 Agent 的执行指令。Agent 会读取并严格遵循这些步骤。
推荐结构
# 技能名称
## 输入参数
- param1: 参数说明
- param2: 参数说明
## 执行流程
### 情况1:xxx
1. 调用 `tool_name`,参数:
- arg1: 说明
- arg2: 说明
2. 根据结果...
### 情况2:xxx
1. ...
## 提示词模板
### 风格1
```
提示词内容...
```
### 风格2
```
提示词内容...
```
## 质量检查清单
- ✅ 必须包含 xxx
- ✅ 必须包含 xxx
- ❌ 禁止 xxx编写原则
- 明确的条件分支:区分有/无参考图、不同风格等情况
- 具体的工具调用:写明工具名和每个参数的值/来源
- 完整的提示词模板:Agent 会直接使用,无需再创作
- 质量检查清单:帮助 Agent 自检输出质量
7. 提示词模板规范
图片提示词要素
✅ 必须包含
- • 年份主题(2026马年)
- • 生肖元素(骏马、金马等)
- • 艺术风格(≥3个关键词)
- • 构图指令(正面/半身/比例)
- • 色彩方案(主色+辅色)
- • 画质指令(4K、精致、高清)
❌ 禁止使用
- • 负面描述(不要、没有、去掉)
- • 英文词汇
- • 错误年份(2024、2025)
- • 其他生肖(蛇、龙等)
- • 模糊描述(好看的、漂亮的)
示例对比
❌ 差的提示词
一张好看的新年贺卡,红色的,不要太复杂
✅ 好的提示词
2026马年国潮贺卡设计,大面积中国红底色, 画面四周环绕精致金色祥云纹边框, 中央区域为主视觉:一匹灵动的金色骏马昂首在牡丹花丛中, 骏马鬃毛飘逸闪烁金光,周围环绕红梅和铜钱, 顶部悬挂大红灯笼串,底部铺满金色如意祥云, 整体色调红金交辉,喜庆热烈又不失精致, 传统纹样与现代设计结合,大师级平面设计品质,4K超清
8. 完整示例
以下是一个完整的技能定义示例(新年贺卡):
---
name: greeting-card
category: image
display_name: 新年贺卡
description: >
生成新年贺卡图片。支持多种风格和自定义文字内容。
icon: image
chain_to:
- blessing-voice
supports_upload: true
output_type: image
inputs:
- key: reference_image
label: 参考图片(可选)
type: image_upload
- key: style
label: 风格
type: style_tags
default: "国潮"
options:
- { value: "国潮", label: "国潮" }
- { value: "极简", label: "极简" }
- { value: "3D", label: "3D" }
- key: text
label: 贺卡文字(可选)
type: text
placeholder: "如:新年快乐、马年大吉..."
- key: aspect_ratio
label: 画面比例
type: style_tags
default: "auto"
options:
- { value: "auto", label: "自动" }
- { value: "1:1", label: "1:1" }
- { value: "4:3", label: "4:3" }
- { value: "16:9", label: "16:9" }
---
# 新年贺卡
## 输入参数
- style: 风格(国潮/极简/3D),默认国潮
- text: 贺卡上要展示的文字(可选)
- reference_image: 参考图片(可选,base64 或 cached:KEY)
- aspect_ratio: 画面比例(可选,auto 表示自动)
## 执行流程
### 有参考图片时
1. 调用 `doubao_analyze_image` 分析参考图片:
- image_base64: 用户提供的 reference_image
- prompt: 「请分析这张图片的构图风格、色调、主要元素」
2. 结合分析结果 + 风格模板 + 文字内容,构建提示词
3. 调用 `seedream_image_to_image`,参数:
- prompt: 构建的提示词
- reference_image: 用户上传的图片
- strength: 0.45
- aspect_ratio: 若用户选择"auto"则不传,否则传用户选择的值
### 无参考图片时
1. 根据风格模板 + 文字内容构建提示词
2. 调用 `seedream_text_to_image`,参数:
- prompt: 构建的提示词
- aspect_ratio: 若用户选择"auto"则不传,否则传用户选择的值
## 提示词模板
### 国潮风格
```
2026马年国潮贺卡设计,大面积中国红底色,
画面四周环绕精致金色祥云纹边框,
中央区域为主视觉:一匹灵动的金色骏马昂首在牡丹花丛中,
{有文字时:画面中上方展示"{text}"文字}
整体色调红金交辉,喜庆热烈,4K超清
```
## 质量检查清单
- ✅ 包含马年生肖元素
- ✅ 包含新年视觉元素(红色、灯笼、梅花等)
- ✅ 明确的艺术风格描述
- ✅ 画质指令(4K)
- ❌ 禁止负面描述
- ❌ 禁止英文9. 上线检查清单
完成以上检查后,重启后端服务即可生效:
pm2 restart seeddream-backend如有问题,请联系开发团队