火宝短剧 prop-prompt 技能规范：白底单品道具最终提示词生成实战指南

导读

本指南以火宝短剧（Huobao Drama）后端 Agent 工作区中的 prop-prompt 技能规范（SKILL.ko.md，另有 中文版 SKILL.md 与 英文版 SKILL.en.md）为骨架，系统讲解「道具白底单品最终提示词」的生成规范与底层实现。读完你将掌握：三条硬性视觉要求（比例准确、边缘完整、背景不承载叙事）、标准产品摄影视角的选用逻辑、单段连贯输出模板，以及 save_prop_final_prompt 工具如何把项目视觉风格自动注入提示词最前端的完整调用链。

技能文件概览：一份面向提示词生成 Agent 的规范

prop-prompt 是注册给 prompt_generator（提示词生成）Agent 的四个子技能之一，与 character-prompt（角色三视图）、scene-prompt（场景固定视角）、video-prompt（视频提示词）并列。它在仓库中的位置为：

backend/workspace/skills/prompt-generator/prop-prompt/
├── SKILL.md      # 中文基础版
├── SKILL.en.md   # 英文变体
├── SKILL.ja.md   # 日文变体
└── SKILL.ko.md   # 韩文变体（本文主体）

文件采用标准 SKILL.md 惯例：frontmatter 声明 name（小写+连字符，符合 Agent Skills 规范）与 description（供技能发现使用），正文即规范全文。韩文版 frontmatter 的 description 准确概括了技能定位：

소품 최종 프롬프트 규범 — 화이트 배경 단품 정물, 표준 제품 사진 시점: 비율 정확, 가장자리 완전, 배경은 서사를 담지 않음 （道具最终提示词规范——白底单品静物，标准产品摄影视角：比例准确、边缘完整、背景不承载叙事）

从 技能注册与加载 的 AGENT_SKILL_MAP 可以看到，prompt_generator 通过前缀 'prompt-generator/prop-prompt' 命中该技能；scanSkillPaths 递归扫描 workspace/skills/ 下所有含 SKILL.md 的目录，这意味着在设置页新建的子技能无需重启即可被发现（backend/src/agents/skills.ts）。

核心目标：一张白底单品图（product shot）

规范开篇即锚定生成物的形态：标准产品摄影视角的白底单品图。画面中只有道具本身，孤立放置在纯白背景上，不掺杂任何其他元素——没有其他物品、没有人物、没有场景环境、没有手部持握。

这一目标通过三条硬性要求落地（韩文版原文为「세 가지 엄격한 요구 사항」，即“三项严格要求”）：

1. 物品各部分比例准确（물건 각 부분의 비율이 정확할 것）——不夸张、不变形、不做风格化拉伸，道具的相对尺寸关系必须真实；
2. 边缘完整（가장자리가 완전할 것）——道具整体完整入镜，四周留白，任何部分都不得被画面边缘裁切；
3. 背景不承载任何叙事内容（배경이 어떤 서사 내용도 담지 않을 것）——纯白背景只是衬底，不带场景感、不带情节暗示、不带装饰元素。

这三条要求共同定义了道具图的“资产属性”：道具图不是剧照、不是氛围图，而是可供后续视频生成与导出流程稳定引用的“外观基准”。正因如此，它与角色图、场景图一起，被 最终提示词服务 定义为生图前必须就绪的三类资产提示词之一。

输出结构：按固定顺序组装单段连贯描述

规范给出了可直接套用的输出模板（韩文版原文）：

단품 제품 이미지, 표준 제품 사진 시점, [소품명 + 재질/색상/형태/크기 + 사용감과 마모 디테일].
물건 각 부분의 비율이 정확하고, 순백 배경 위에 고립되어 놓여 있으며, 중앙에 온전히 들어오고, 가장자리가 완전하여 잘림이 없음.
배경은 깨끗하고 어떤 서사 내용도 담지 않으며, 다른 물건 없음, 인물 없음, 장면 없음.
부드럽고 고른 스튜디오 조명, 옅은 그림자, 고디테일

对应中文版 SKILL.md 的可读对照模板为：

单品产品图，标准产品摄影视角，[道具名 + 材质/颜色/形状/大小 + 新旧程度与磨损细节]，
物品各部分比例准确，孤立放置在纯白背景上，居中完整入镜，边缘完整无裁切，
背景纯净不承载任何叙事内容，无其他物品、无人物、无场景，
柔和均匀的影棚光，轻淡阴影，高细节

模板的关键约束是**“按此顺序组装单段连贯描述”**：不能分点、不能打散，要组装成一个自然连贯的提示词段落；输出语言跟随会话语言指令（session language directive），即本次会话指定的目标语言。这与 prompt_generator 通用规范 中“所有提示词使用会话语言指令指定的目标语言输出，单段连贯描述，不要分点，不要混入无关词汇”完全一致。

模板的四个组成块，每一块都对应一种视觉职责：

模板块	视觉职责
单品产品图，标准产品摄影视角	定调“产品图”而非“剧照”
道具名 + 物理细节（材质/颜色/形状/大小/新旧/磨损）	承载道具辨识度
比例准确、纯白背景、居中完整、边缘无裁切	落实三条硬性要求
柔和均匀的影棚光、轻淡阴影、高细节	统一光照基调

生成规则：让道具“看得清、认得准”

规范在生成规则一节给出了六条实操准则：

• 以道具 name 与 description 为核心：材质、颜色、形状、大小、新旧程度、磨损痕迹等物理细节必须逐项落地——这是道具辨识度的来源。此处的 name/description 对应数据库中 props 表的字段，由 readProps 工具 从 schema.props 读取并返回给 Agent（含 type、final_prompt 等字段）；
• 标准产品摄影视角：采用微俯视 3/4 视角（同时看清顶面与侧面，最有立体感）；扁平道具（纸张、证件、照片）改用正俯视平铺（flat lay）；
• 单品居中完整呈现：四周留白，比例准确、边缘完整，不裁切道具主体；
• 柔和均匀的影棚光：阴影轻淡，高细节；
• 只描写物品本身：不要提及剧情、角色或用途——背景与画面都不承载叙事内容；
• 不混入无关词汇：不要使用“电影质感”类词汇——道具图是产品图，不是剧照。

其中“只描写物品本身”与提取器 Agent（extractor）的字段约束呼应：extractor 指令明确要求道具 description“只描写物品本身的物理外观——材质、颜色、形状、大小、新旧程度、磨损痕迹等，不要写剧情用途”（backend/src/agents/index.ts）。可见从数据采集端到提示词生成端，整条链路都贯彻“道具 = 物理外观基准”的同一原则。

禁止事项：五类必须剔除的内容

规范列出五条明确的禁令（韩文版原文「금지 사항」），可作为生成结果的质检清单：

1. 手部持握、人物、其他物品、场景环境入镜——画面只允许道具本身；
2. 包装、底座、展示架——除非它们本身就是道具本体的一部分（如“带底座的奖杯”）；
3. 文字、水印、签名——但道具本体上印刷的文字图案可以保留并描述（如证件上的姓名信息）；
4. 环境反光、彩色光——只允许干净中性的影棚光照；
5. 夸张透视、变形、比例失真、边缘裁切——与三条硬性要求中的前两条互为镜像。

这五条禁令本质上是把“白底单品”的边界彻底划清：既防“内容越界”（混入人物/场景/包装），也防“画质越界”（反光、彩色光、透视变形）。

保存流程：风格由工具注入，prompt 只含内容

规范的收尾章节规定了保存动作：

调用 save_prop_final_prompt：prompt 参数中不包含风格词，项目视觉风格由工具自动注入到最终提示词的最前方。

这是整套规范中“规范层”与“实现层”的接缝处。在实现层，savePropFinalPrompt 工具 的完整执行逻辑为：

1. 从请求上下文读取 dramaId（缺失即报错）；
2. 按 prop_id 查询 props 表，未找到则返回 Prop not found；
3. 调用 getDramaStylePrompt(dramaId) 获取项目绑定的风格预设；
4. 执行拼接：finalPrompt = stylePrompt ? \${stylePrompt}, ${prompt}` : prompt`——风格词在前，Agent 产出的提示词在后，与规范“注入到最终提示词的最前方”完全一致；
5. 写回 props.finalPrompt 并返回 { prop_id, prop_name, saved, final_prompt }。

其中 getDramaStylePrompt 的实现是从 dramas.style 解析出风格预设值，再查询 style_presets 表中 isActive = true 的预设记录，返回其英文提示词片段；查不到或已停用时返回空串，此时工具退化为只保存 Agent 原文。

save_prop_final_prompt 与 save_character_final_prompt、save_scene_final_prompt 一起被导出为 imagePromptTools（backend/src/agents/tools/image-prompt-tools.ts），并整体挂载到 prompt_generator Agent 的工具表（backend/src/agents/index.ts）。

源码级调用链：从资产缺提示词到生图就绪

prop-prompt 技能不是孤立文档，它处于一条完整的自动补全链路上。核心入口是 ensurePropFinalPrompt：

prop.finalPrompt 已存在且非 force → 直接复用
否则 → 向 prompt_generator Agent 发送：
       "为道具「name」(prop_id=..) 生成白底单品最终提示词，并调用 save_prop_final_prompt 保存"
       然后回读 props.finalPrompt
失败 → 记日志，返回 ''，由调用方回退到本地拼接提示词

该服务通过 runPromptAgent（backend/src/services/final-prompt.ts）取得 Mastra 注册的 prompt_generator Agent，以 maxSteps: 12 的步数上限允许 Agent 完成多轮“读资产 → 创作 → 保存”的工具调用。Agent 的系统指令（backend/src/agents/index.ts）则明确要求：先 read_props 读取道具信息，再按对应资产的技能规范创作（此处即 prop-prompt 技能），最后调用保存工具——必须实际调用保存工具，不要只在回复中给出提示词。

ensurePropFinalPrompt 的调用方包括道具生图路由 POST /props/:id/generate-image（backend/src/routes/props.ts）：该路由先生成最终提示词（缺失时触发 Agent 创作），再以 prompt = finalPrompt || propImagePrompt(prop, stylePrompt) 的兜底策略调用 generateImage。也就是说，prop-prompt 技能的产出质量直接决定了道具参考图的生成输入。

多语言变体机制：SKILL.ko.md 如何被加载

本指南主体 SKILL.ko.md 之所以能生效，依赖 readLocalizedSkill 与 loadAgentSkills 的变体读取逻辑：

• 会话语言非中文时，逐技能优先读取 SKILL.<lang>.md（如 SKILL.ko.md、SKILL.ja.md、SKILL.en.md），文件不存在则回退中文基础版 SKILL.md；
• 变体读取走 stripFrontmatter 剥离 frontmatter 后直读正文，绕缓存保证永远最新；
• 技能全文最终以 ## Skill: <relPath> 节的形式拼接进 Agent 的 instructions，与基础指令、语言指令块一起按请求动态注入（backend/src/agents/index.ts）。

这也意味着：若在设置页修改某个语言变体的内容，无需重启即可生效；同一技能在不同语言会话下会呈现对应语言的规范文本，确保多语言输出的一致性。

实战要点速查

• 三查一验：生成前对照三条硬性要求（比例/边缘/背景）逐一检查描述是否落实；生成后用五条禁令做反查清单；
• 视角选择：立体道具用微俯视 3/4 视角，扁平道具（纸张、证件、照片）用正俯视平铺；
• 物理细节逐项落地：材质、颜色、形状、大小、新旧程度、磨损痕迹一个不落，这是与故事中其他同型物品区分的关键；
• 语言与文体：输出语言跟随会话语言指令，单段连贯描述，禁用“电影质感”类词汇；
• 保存纪律：只调用 save_prop_final_prompt 且 prompt 参数不含风格词——项目视觉风格由工具自动注入最前端；不实际调用保存工具即视为未完成任务。

小结

prop-prompt 技能用一页精简规范，把“道具参考图”从模糊的“画个物品”收敛为可执行、可校验、可自动化的工程标准：三条硬性要求定义视觉底线，输出模板保证格式一致，五条禁令充当质检清单，save_prop_final_prompt 完成“内容与风格分离”的保存闭环。结合 技能注册、提示词工具、最终提示词服务 与 道具生图路由 的源码，可以看到这条从资产数据到生图输入的链路是完整自洽的——这正是火宝短剧“一句话生成完整短剧”流水线中，道具资产能被稳定复用与引用的底层保障。