提示词模板与风格包
本文属于“当前架构”文档,描述当前已经生效的提示词模板机制。
模板存在数据库里
提示词模板不再硬编码在代码中,而是作为数据行存在 prompt_templates 表:
| 列 | 类型 | 说明 |
|---|---|---|
id | varchar(64) | 主键 |
category | varchar(32) | 模板类别,业务侧按类别查找 |
name | varchar(255) | 展示名 |
preview | text | 预览用短文本 |
content | text | 模板正文,含 {{ 变量 }} |
variables | json | 本模板声明的变量列表 |
is_default | tinyint(1) | 是否默认模板 |
is_system | tinyint(1) | 是否系统内置 |
published_at | datetime(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.sql028 会先创建 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)(与 SQLAlchemyDateTime(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_PACKS | 7 个中文题材 | 按项目 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) -> boolstyle_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 增加,角色详情表单的标签字段会进入角色卡提示词。