AI 创意工坊

马年大吉
返回首页

技能开发指南

了解如何创建新技能,让 AI 创意工坊支持更多场景

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技能描述,支持多行
iconLucide 图标名: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: true
select

下拉选择

下拉选择框,适合选项较多的场景

- 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: 1
number

数字输入

数字输入框,支持最小/最大值限制

- key: count
  label: 数量
  type: number
  default: 3
  min: 1
  max: 10
voice_picker

语音选择

语音类型选择卡片(用于 TTS 技能)

- key: voice_type
  label: 音色
  type: voice_picker

5. 可用工具

📖read_file

读取文件内容(Agent 自动调用读取 SKILL.md)

参数:

path (string) - 文件路径

返回:文件内容字符串

✍️doubao_generate_text

调用豆包大模型生成文本(春联、祝福语、签文等)

参数:

system_prompt (string) - 系统提示词
user_message (string) - 用户消息

返回:生成的文本内容

🔍doubao_analyze_image

调用豆包多模态模型分析图片

参数:

image_base64 (string) - 图片 base64 或 cached:KEY
prompt (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:KEY
strength (number) - 变化强度 0-1(0.3 大变化,0.7 小变化)
aspect_ratio (string?) - 可选,画面比例

返回:cached:KEY(图片缓存引用)

🎬seedance_image_to_video

图生视频 - 将首帧图片转为动态视频

参数:

first_frame (string) - 首帧图片 base64 或 cached:KEY
duration (number) - 时长(秒)
aspect_ratio (string?) - 可选,画面比例

返回:视频 URL

🎙️tts_synthesize

文字转语音

参数:

text (string) - 要朗读的文本
voice_type (string) - 音色 ID
speed_ratio (number) - 语速 0.5-2.0
volume_ratio (number) - 音量 0.5-2.0
pitch_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

如有问题,请联系开发团队