Skip to content
提示词模板与风格包

提示词模板与风格包

本文属于“当前架构”文档,描述当前已经生效的提示词模板机制。

模板存在数据库里

提示词模板不再硬编码在代码中,而是作为数据行存在 prompt_templates 表:

列类型说明
idvarchar(64)主键
categoryvarchar(32)模板类别,业务侧按类别查找
namevarchar(255)展示名
previewtext预览用短文本
contenttext模板正文,含 {{ 变量 }}
variablesjson本模板声明的变量列表
is_defaulttinyint(1)是否默认模板
is_systemtinyint(1)是否系统内置
published_atdatetime(6)发布时间(非空 = 已发布到运行时;仅 agent_* 分类使用),写入语义固定为 UTC(迁移 017)

索引为 ix_prompt_templates_category、ix_prompt_templates_name。注意 category 上没有唯一键,因此写入迁移必须是幂等的 UPDATE ... WHERE category = 'x' 配合 INSERT INTO ... SELECT ... FROM DUAL WHERE NOT EXISTS (SELECT 1 FROM prompt_templates WHERE category = 'x')。

图片 / Agent 模板共 27 个类别(PromptCategory 还包含 video_prompt、storyboard_prompt、bgm、sfx 等非图片类别):

actor_image_front        actor_image_other
character_card           character_image_front    character_image_other
prop_image_front         prop_image_other
scene_image_front        scene_image_other
costume_image_front      costume_image_other
combined
frame_head_prompt        frame_tail_prompt        frame_key_prompt
agent_script_division    agent_element_extract    agent_character_portrait
agent_scene_info         agent_prop_info          agent_costume_info
agent_consistency_check  agent_entity_merge       agent_script_optimize
agent_script_simplify    agent_variant_analyze    agent_h3_video

为什么 video_prompt 故意不播种

一旦库里存在 video_prompt 行,derive_video_preview 就会走模板分支,从而绕过 IR → H3 渲染器这条链路(见视频提示词链路)。所以它被有意留空。

迁移由代码生成,不手抄

模板正文要求与代码里的常量逐字一致,手抄必然漂移。因此迁移文件是生成物:

cd backend && .venv/bin/python scripts/gen_prompt_templates_sql.py
# 新增单个分类时只生成该分类,避免重写全部资产模板:
cd backend && .venv/bin/python scripts/gen_prompt_templates_sql.py \
  --output 055-add-character-card-prompt.sql \
  --title "055-add-character-card-prompt.sql" \
  --only character_card

脚本 backend/scripts/gen_prompt_templates_sql.py 会:

  • import 三个帧模板常量(_FIRST_FRAME_TEMPLATE / _LAST_FRAME_TEMPLATE / _KEY_FRAME_TEMPLATE)以及 _SHOT_FRAME_INPUT_VARS,保证 SQL 与运行代码同源;
  • 用统一的 ASSET_VARS 描述资产类模板变量;
  • 默认输出 backend/sql/028-rewrite-image-prompt-templates.sql(012 是已应用的种子,不再改写)。

Agent 提示词种子同样由生成器产出:gen_agent_prompt_templates_sql.py 默认输出 029-update-h3-agent-prompt.sql,--full 才额外生成 015 全量种子。两者都直接 import 各 Agent 的 _*_SYSTEM_PROMPT 常量,避免手抄漂移。

生成物与代码的一致性由一个只读校验脚本把关:backend/scripts/check_agent_prompt_templates_sql.py 解析 015 里的 UPDATE 语句、还原被转义的内容,再与生成器内存中的 AGENT_TEMPLATES 逐字比对;它不写文件,退出码 0 = 完全一致、1 = 存在差异或解析失败(可直接挂进 CI)。

为什么必须校验:如果只改代码不改 SQL,用户在模板页不改内容直接点「发布生效」,就会把 015 里的旧提示词写进运行时。

应用方式:

# 新部署:012 建种子
docker exec -i compose-mysql-1 mysql -uroot -p"$DB_PASS" --default-character-set=utf8mb4 dyeingtime \
  < backend/sql/012-rewrite-prompt-templates.sql

# 已有部署:028 更新图片模板,029 更新未发布的 H3 Agent 默认提示词
docker exec -i compose-mysql-1 mysql -uroot -p"$DB_PASS" --default-character-set=utf8mb4 dyeingtime \
  < backend/sql/028-rewrite-image-prompt-templates.sql
docker exec -i compose-mysql-1 mysql -uroot -p"$DB_PASS" --default-character-set=utf8mb4 dyeingtime \
  < backend/sql/029-update-h3-agent-prompt.sql

028 会先创建 prompt_templates_backup_028 备份表,再更新图片模板;需要回滚时可直接从备份表恢复。029 / 032 / 033 只更新 published_at IS NULL 的 Agent 模板(H3 视频、分镜拆解、剧本优化/精简);已发布的自定义版本不会被静默覆盖。

迁移可重复执行:跑第二次不会新增行,SELECT COUNT(*) FROM prompt_templates 仍是 26。

Agent 提示词的发布机制

agent_* 这 12 个类别对应 12 个运行时 Agent 的系统提示词(分镜拆解、要素提取、角色画像、场景/道具/服装信息、一致性检查、实体合并、剧本优化/简化、变体分析、H3 视频提示词)。它们的权威默认值仍硬编码在各 Agent 的 _*_SYSTEM_PROMPT 常量里,但可以通过模板页编辑并发布,覆盖代码默认。

生效模型(用户侧语义为「保存后手动触发生效」):

动作效果
模板页「发布生效」写 published_at(UTC),并更新当前进程缓存;下一次生成任务(API 进程直接触发)即用新提示词
「发布生效」的前置校验内容为空 / 纯空白时拒绝发布(否则 agent 会静默降级为「无 system prompt」)
「发布生效」的分类去重发布时把同分类其他行的 published_at 一并置空,保证「同一分类下至多一条已发布」
编辑已发布模板的内容published_at 被置空(退回未发布),同时清掉本进程缓存里该 agent 的旧内容——改了就自动下线,必须重新发布才生效;未发布的模板只改内容,不涉及 published_at
编辑接口传入空内容直接拒绝(与发布同一套空内容校验)
Celery worker 任务执行每个任务在执行前统一调用刷新钩子,从 DB 拉已发布模板,保证跨进程一致(见任务执行架构)
API 启动lifespan 中把加载已发布模板改为后台任务,不再阻塞启动;预热失败只记 warning,不影响服务可用性
模板页「恢复默认」清 published_at 并移除缓存,回落代码内置默认

关键实现:

  • backend/app/chains/agents/prompt_registry.py:agent_key ↔ PromptCategory 映射、进程内缓存(_cache: dict[str, str])、发布/恢复/刷新函数(含同步版供 Celery worker 使用)。
  • 刷新的「是否需要重新拉取」判据:用显式的一次性标记 _loaded_once(本进程是否已成功拉取过一次,无论结果是否为空),不再用「缓存是否为空」。否则所有模板都「恢复默认」时缓存被清空,每个任务入口都会判为「需要刷新」,TTL 形同失效、每次都查库。TTL 为 _CACHE_TTL_SECONDS = 10.0,发布/恢复默认走 publish/reset 直接精确更新本进程缓存,不受 TTL 延迟。
  • 刷新查询有确定的排序:按 published_at ASC, id DESC(_published_order_by())加载,同分类存在多行已发布时由「后写入者覆盖前者」决定最终生效内容,id 作为同秒并列时的稳定 tiebreaker;行为不再依赖数据库返回顺序。正常路径下发布已清空同分类其它行,该排序只是兜底。
  • AgentBase.system_prompt:registry.get_agent_prompt(agent_key) 命中则返回发布内容,否则回落子类 _default_system_prompt();子类只需声明 agent_key 并把原 system_prompt 改名 _default_system_prompt。
  • published_at 只表达「已发布」,与 is_default(生成类模板的默认选择)解耦;agent_* 模板 is_system=0,允许编辑(发布后才影响运行时)。
  • 迁移 backend/sql/017-normalize-prompt-template-published-at-timezone.sql 把 published_at 由 DATETIME 统一为 DATETIME(6)(与 SQLAlchemy DateTime(timezone=True) 在 MySQL 上的实际类型一致,并保留微秒精度),写入值语义固定为 UTC 墙钟;读取路径只判断 IS NOT NULL 与相对排序,不依赖绝对时区偏移,因此历史行无需回填(回填反而会破坏「已发布」语义)。该迁移只做无条件 MODIFY COLUMN,可重复执行。

变量契约

资产类模板(角色 / 演员 / 场景 / 道具 / 服装 / combined)共享同一组变量:

name  description  tags  visual_style  style
view_angle  quality_level  format  style_pack  reference_block  negative_prompt

模板正文统一为「交付物 → 参考图角色 → 主体与细节 → 统一约束」:

[交付物]
角色定妆照:正面平视半身,纯色中性背景……

[参考图角色]
图1 为「演员甲」的正面身份参考……
图2 为「黑色风衣」的正面服装形制参考……

[主体与细节]
……

[Constraints]
保持面部五官、发型发色、肤色与年龄感不变
画面内不出现文字、字幕、水印或 UI
避免出现:{{ negative_prompt }}

非正面视角模板必须先写「仅修改:视角」再写「保留:五官/发型/服装/背景/光照/比例」,避免整张图自由漂移。reference_block 由 asset_image/build_base.py 根据实际参考图顺序生成,不再由模板手写编号。

这里有一个历史坑:早期模板正文用了 {{ view }} 和 {{ extra_details }},但这两个变量从未被传进 variables。渲染时 render_prompt_template_content 会把未知变量渲染成空字符串,于是“镜头方向:”后面一直是空的。新模板统一改用实际会传入的 view_angle / tags / style_pack / negative_prompt。

修改模板变量时,务必同步 ASSET_VARS 与调用侧的 variables 字典——两边不一致就是静默的空字符串。

项目级风格包

backend/app/chains/prompts/style_pack.py 提供“一处配置、全局注入”的风格层:

常量键说明
FORMAT_PACKS现实 / 动漫按项目 visual_style
STYLE_PACKS7 个中文题材按项目 style

对外函数:

def format_pack_for(visual_style) -> str
def motif_pack_for(style) -> str
def style_pack_line(*, visual_style="", style="") -> str
def negative_image_prompt(*, visual_style="", style="") -> str
def is_anime(*, visual_style, style) -> bool

style_pack_line 用「;」拼接题材包与形态包,永远非空(找不到就回落到 DEFAULT_STYLE_PACK = STYLE_PACKS["真人都市"] / DEFAULT_FORMAT_PACK = FORMAT_PACKS["现实"]),因此模板里的 {{ style_pack }} 不会渲染成空。

字段语义(容易搞混,务必分清)

backend/app/models/types.py 里:

  • ProjectStyle → 对应 style 字段,取值 真人都市 / 真人科幻 / 真人古装 / 动漫科幻 / 动漫3D / 国漫 / 水墨画。
  • ProjectVisualStyle → 对应 visual_style 字段,取值只有 现实 / 动漫。

app.models.types 里没有 VisualStyle 这个名字。给 style_pack_line 传参时不要把两者对调。

命名约定

  • _ANIME_FORMATS = {"动漫"}
  • _ANIME_STYLES = {"动漫科幻", "动漫3D", "国漫", "水墨画"}
  • _ANCIENT_STYLES = {"真人古装"}

统一负面提示词

同一模块提供四组负面词常量:

COMMON_NEGATIVE_IMAGE
REALISTIC_NEGATIVE_IMAGE
ANIME_NEGATIVE_IMAGE
ANCIENT_NEGATIVE_IMAGE

由 negative_image_prompt(*, visual_style, style) 用「,」拼成一条,写进模板变量 negative_prompt,并由每个模板的 [Constraints] 段消费:

[Constraints]
...
避免出现:{{ negative_prompt }}

分镜帧链路不经过资产模板:基础提示词只写画面,最终渲染由 frame/derive_preview.py 追加 [参考图角色] 与 [统一约束],其中统一约束会合并 negative_prompt、DEFAULT_PRESERVE_ITEMS、DEFAULT_AVOID_ITEMS 与「画面无文字」规则。

刻意不写的东西

风格包只描述画面可观察要素,不写“8K 分辨率”“f/1.4 大光圈”这类参数:当前出图统一 1K,且主流出图模型对光圈数值不敏感,写了只是噪音。

角色卡

角色默认生成一张 16:9 正面全身角色卡,使用 character_card 模板:

  • 只允许一个人物、一个完整人体;
  • 从头到脚完整入镜,人物居中,左右保留安全边距;
  • 不生成三视图、拼图、分屏或镜像分身;
  • 带参考图时,参考图作为身份基准,不重新设计面容;
  • 模板变量包含 name、description、tags、reference_block、style_pack、negative_prompt 等。

角色图基础草稿由 build_character_image_base_draft(backend/app/services/studio/generation/asset_image/build_base.py)构造:

  • 正面视角使用 PromptCategory.character_card;
  • 非正面视角使用 PromptCategory.character_image_other,并绑定角色卡作为「正面基准」;
  • 角色绑定演员 + 服装时,reference_block 会分别写清演员身份参考与服装形制参考;
  • 候选 generation_params.image_kind 记录 character_card / character_angle,用于前端展示与审计。

character_image_front 保留为历史兼容模板:旧客户端或历史任务仍可读取,但新角色卡不再走该分类。characters.tags 由迁移 058 增加,角色详情表单的标签字段会进入角色卡提示词。

相关文档