astrbot_plugin_imagestudio/docs/material-composition-prompt-routing-development-queue.md

24 KiB

ImageStudio 素材编译、提示词转译与模型分流开发队列

状态:已完成(2026-07-12)
建立日期:2026-07-12
依据:astrbot_imagestudio_asset_materials_focus_doc_v1.md 与当前 ImageStudio 后端实现审计
目标:升级“素材识别 → 素材库 → 角色拼装 → 提示词转译 → 内容审核 → 模型路由 → 生图”完整链路。

1. 当前实现审计结论

当前系统已经具备素材上传、视觉识别、人工确认、素材分类、角色衣橱、素材匹配、工作流节点绑定、参考图注入、静态模型路由、提示词合并和生成结果审核基础能力。

当前主要缺口:

  • 素材识别结果仍以单份 prompt / negative_prompt / tags 为主,没有 RawAnalysis、NormalizedAssetProfile、GenerationCapsule 三层结构。
  • 视觉模型完整结构化返回没有被持久保存,无法可靠地重新标准化或逐项人工修正。
  • 衣橱匹配后仍通过字符串连接形成 outfit_prompt,没有身体槽位、穿着层级、冲突解决和提示词预算。
  • 现有素材 reference strength 只表示参考图强度,不等于素材语义优先级。
  • 多张参考图没有 role / use_for / do_not_inherit 职责约束。
  • PromptExpansionService 只负责合并提示词,没有中文到英文的语义转译层。
  • 现有模型路由主要按节点、角色或设置静态选择,不能根据提示词审核结果动态分流。
  • 现有 review 主要用于工作流、候选图和结果质量审核,不是生成前提示词内容审核。

2. 总体目标链路

用户中文需求
  → 原始需求保存
  → 用户授权检查
  → 语义转译与提示词结构化
  → 合规语义规范化(降低歧义和误报,不绕过安全策略)
  → 素材 CompositionBuilder 编译
  → 生成前内容审核
  → 风险分级与路由决策
      ├─ 普通内容 → 默认生图模型
      ├─ 允许的成人内容 → 自动分流到已配置 NSFW 模型
      ├─ 不确定内容 → 人工确认或保守路由
      ├─ 恐怖主义 / 暴力宣扬 / 极端血腥 → 拒绝生成并警告
      └─ 其他禁止内容 → 拒绝生成
  → 生图
  → 生成后图片审核
  → 返回、隔离、重试或拒绝

3. P0:素材三层数据结构

  • 定义 RawAnalysis DTO 与 JSON Schema。
  • 定义 NormalizedAssetProfile DTO 与 JSON Schema。
  • 定义 GenerationCapsule DTO 与 JSON Schema。
  • 为三层数据增加 schema_version、prompt_version、created_at 和模型来源。
  • 扩展 VisionRecognitionResult,保留视觉模型完整结构化结果。
  • 将完整原始识别结果写入素材 metadata,而不是只保存响应键名。
  • 增加视觉模型返回 JSON Schema 校验。
  • 增加可修复 JSON 的有限修复流程;无法修复时明确失败,不生成伪结构。
  • 区分 observed / inferred / unknown / occluded / low_visibility。
  • 实现 0.60 与 0.80 置信度分层规则。
  • 低置信度和推测属性默认不得进入生图输入。
  • 实现 MaterialNormalizationService。
  • 建立类别、服装类型、颜色、长度、版型、材质等同义词归一表。
  • 自动生成 Compact、Standard、Detailed 三档 Generation Capsule。
  • 旧素材根据现有 prompt 自动生成 Legacy Capsule,保证无破坏迁移。
  • 重新识别时保留历史版本和人工修改,不直接覆盖已确认结构。

4. P0:素材语义、身体槽位与穿着层级

  • 定义稳定的素材 category 枚举。
  • 定义素材 role 枚举。
  • 定义身体槽位:identity、hair、head、face、ears、neck、upper_body、arms、hands、waist、hips、upper_legs、lower_legs、feet、pose、background、global_style。
  • 定义穿着层级:skin、inner、base、middle、outer、overlay、accessory、prop。
  • 建立现有素材分类到标准类别、角色、槽位和层级的映射。
  • 建立衣橱分类到标准语义的映射。
  • 支持用户在确认素材时修正类别、角色、槽位和层级。
  • 为连衣裙、套装、外套、内搭、首饰、鞋靴和道具增加专门规则。
  • 对未知分类使用 other,并要求确认后再参加自动拼装。

5. P0:CompositionBuilder 素材拼接器

  • 新建 CompositionPlan DTO。
  • 新建 CompositionResult DTO。
  • 新建 CompositionBuilder 或 OutfitPromptCompiler 服务。
  • 将角色身份作为最高优先级输入。
  • 从衣橱匹配结果读取素材,而不是直接连接素材 prompt。
  • 从素材读取 Generation Capsule。
  • 按身体槽位对素材分组。
  • 按穿着层级排序。
  • 实现连衣裙与独立上衣、下装冲突检测。
  • 实现同身体槽位多素材冲突检测。
  • 支持配饰可叠戴和不可叠戴规则。
  • 实现同一属性值矛盾检测,例如 fitted/oversized、matte/glossy。
  • 冲突解决遵循:用户锁定 > 人工修正 > 高置信观察 > 中置信观察 > 推测。
  • 记录保留、降级、忽略素材及具体原因。
  • 按统一顺序编译身份、发型、体型、内搭、外套、下装、鞋靴、配饰、姿势、场景、风格和光线。
  • 将 must_preserve 编译为明确约束段。
  • 将 forbidden_changes 编译到负向提示词或禁止变化段。
  • 输出 resolution_log、conflicts、ignored_materials 和 downgraded_materials。
  • 接入快速角色、详细角色和单图生成流程。

6. P0:素材权重系统

  • 定义角色身份、主服装、连衣裙、下装、发型、鞋靴、配饰、姿势、画风和背景的默认基础权重。
  • 将衣橱“匹配得分”和生成“语义权重”拆成两个独立概念。
  • 增加 user_adjustment。
  • 增加素材锁定状态和 lock_bonus。
  • 增加主服装、身份素材等 role_bonus。
  • 根据当前构图和节点增加 visibility_bonus。
  • 根据冲突结果计算 conflict_penalty。
  • 根据置信度和推测状态计算 low_confidence_penalty。
  • 计算 effective_weight 并保留计算明细。
  • 根据最终权重决定胶囊档位、提示词顺序和参考图保留状态。
  • 保留现有 strong/medium/weak 作为模型参考图强度,不与素材语义权重混用。

7. P0:用户授权与提示词转译层

  • 新建 PromptTranslationService,放在原始用户输入与 CompositionBuilder/PromptExpansionService 之间。
  • 设置页面增加“启用 LLM 提示词转译”总开关,默认关闭或要求用户明确启用。
  • 分别配置 Web、QQ、Telegram、Discord 等入口是否允许自动转译。
  • 保存用户原始输入、转译结果、模型、模板版本和时间,便于追踪与回滚。
  • 原始输入始终保留,不允许转译层静默改变用户核心意图。
  • 支持中文需求转为面向目标生图模型的英文提示词。
  • 支持自动拆分主体、外观、服装、动作、构图、场景、画风、光线、镜头和负向约束。
  • 支持对 CompositionBuilder 的结构化结果进行英文编译,而不是对最终长字符串盲目翻译。
  • 支持模型专用转译模板,例如自然语言型、标签型、SD 权重型。
  • 支持专有名词、角色名、品牌名和用户锁定词“不翻译/固定翻译”词典。
  • 支持中英文混合输入和仅英文输入直通。
  • 支持转译前后差异摘要。
  • 用户可选择“直接使用原文 / 使用转译 / 手动编辑后使用”。
  • 转译失败时安全回退到原始输入,不得生成空提示词。
  • 对转译服务设置超时、重试、token 预算和成本审计。

8. P0:合规语义规范化层

本层用于降低歧义、减少无意误报并保持需求效果,不用于隐藏禁止内容或绕过模型、平台及服务商的安全审核。

  • 新建 PromptSemanticNormalizer,与翻译服务解耦。
  • 将容易产生歧义的口语转换为准确、中性的视觉描述。
  • 将年龄、人物身份、身体状态等高风险歧义显式化,避免模型误判。
  • 对合法成人题材使用明确的“成年角色”约束。
  • 对摄影、医学、艺术、泳装、舞台服装等合法上下文补充必要语境。
  • 不允许删除或伪装会改变安全分类的核心语义。
  • 不允许将被禁止内容改写成隐语、编码词或规避词。
  • 保留改写前后文本及改写理由。
  • 用户锁定的核心视觉效果不可被无提示删除。
  • 如果规范化会显著改变需求,必须要求用户确认。
  • 为每次规范化输出 changed_terms、reason、meaning_preserved。

9. P0:生成前提示词审核层

  • 新建 PromptModerationService,在最终模型路由确定前执行。
  • 审核对象包含原始输入、转译输入、CompositionResult、负向提示词和参考图职责。
  • 审核返回结构化类别、置信度、风险等级、原因和处置建议。
  • 风险等级至少区分 safe / sensitive / adult_allowed / uncertain / violence_prohibited / terror_prohibited / prohibited。
  • 区分合法成人内容与禁止内容,禁止内容不得通过 NSFW 路由继续生成。
  • 单独识别恐怖主义宣传、招募、赞美、威胁和现实行动引导。
  • 单独识别暴力宣扬、针对现实目标的伤害威胁和高危暴力行动请求。
  • 单独识别以极端血腥、肢解、酷刑为核心表现目的的内容。
  • terror_prohibited 与 violence_prohibited 必须直接拒绝,不允许进入普通或 NSFW 生图模型。
  • 恐暴拒绝响应必须返回明确警告,同时避免复述可操作的危险细节。
  • 恐暴命中写入高优先级安全审计事件,包含入口、用户、群聊、分类和规则版本。
  • 对涉及未成年人或年龄不明确的成人内容采用拒绝或人工确认策略。
  • 对高风险但不确定内容进入保守策略,不自动选择宽松模型。
  • 支持规则审核与 LLM/VLM 审核组合。
  • 规则结果与模型审核冲突时采用更严格结果,或按配置进入人工确认。
  • 审核服务失败时采用 fail-closed 或由管理员明确配置的保守回退。
  • 将审核决策写入任务 metadata 和审计日志,但敏感原文按日志脱敏策略保存。
  • 增加审核模板和分类版本号。

10. P0:普通与 NSFW 生图模型动态分流

  • 设置页面增加“内容审核与模型分流”配置栏。
  • 增加默认安全生图路由选择。
  • 增加允许成人内容的 NSFW 生图路由选择。
  • NSFW 路由只能选择管理员明确标记为允许成人内容的已配置适配器和模型。
  • 增加“是否允许成人内容自动分流”开关,默认关闭;管理员开启后,对通过审核与权限检查的 adult_allowed 内容自动执行分流。
  • 增加不同入口、群聊、用户和角色工作流的成人内容权限开关。
  • 成人内容分流同时受现有用户白名单、群聊白名单和额度策略约束。
  • 实现 GenerationRouteDecision:requested_route、moderation_level、selected_route、reason、fallback_route。
  • safe/sensitive 默认进入普通模型。
  • adult_allowed 且用户、入口、管理员策略全部允许时自动进入 NSFW 模型,无需再次手动选择模型。
  • uncertain 默认要求确认或拒绝,不自动分流到 NSFW 模型。
  • violence_prohibited、terror_prohibited 和 prohibited 始终拒绝,不进入任何生图模型。
  • NSFW 模型只承接允许的成人内容,不得作为恐怖、暴力或其他禁止内容的兜底模型。
  • 未配置 NSFW 路由时返回明确错误,不偷偷回退到普通模型。
  • 增加 GenerationFailureClassifier,将普通模型失败至少拆分为 content_safety_rejection / rate_limit / quota_exhausted / authentication / invalid_request / unsupported_capability / timeout / upstream_error / unknown,保留供应商状态码、错误码和脱敏错误摘要。
  • 普通模型返回失败时先判断失败类型;网络、超时、额度、鉴权、参数、能力不支持和未知错误不得触发 NSFW 路由。
  • 当供应商明确返回成人内容或内容安全拒绝信号时,重新调用 PromptModerationService 复核原始提示词、转译提示词和实际发送提示词,不能仅凭模糊的供应商报错改投 NSFW。
  • 二次审核结果为 adult_allowed,且管理员开关、入口权限、用户/群聊白名单、额度策略和 NSFW 路由配置全部通过时,允许从普通模型单次回退到 NSFW 模型尝试。
  • 二次审核为 uncertain 时要求确认或拒绝;为 violence_prohibited / terror_prohibited / prohibited 时直接禁止并警告,不得回退。
  • 普通模型到 NSFW 模型的失败回退最多执行一次,记录 initial_route / failure_class / moderation_recheck / fallback_route / fallback_reason,禁止循环切换模型。
  • NSFW 回退也失败时返回明确的最终失败原因,不再自动投递其他成人模型;是否允许人工重试由管理员策略决定。
  • 动态路由决策必须发生在成本检查、任务入队和模型解析前。
  • 将最终路由原因写入任务、图片和聊天审计记录。

11. P1:生成后图片审核

  • 新建独立的 ImageModerationService,不要复用工作流质量审核结果冒充内容审核。
  • 对普通模型和 NSFW 模型生成结果采用不同但明确的审核策略。
  • 审核生成图片是否超出请求允许范围。
  • 审核生成结果是否出现年龄不明、禁止内容或意外裸露。
  • 结果分为允许返回、警告返回、隔离、重新生成和拒绝返回。
  • 聊天端返回前执行图片审核。
  • Web 图库对受限结果增加权限控制和遮罩。
  • 隔离图片不进入普通图库、角色封面和素材库。
  • 为误判提供管理员复核流程。
  • 保存审核模型、分类、置信度和版本,但避免不必要地复制敏感图片。

12. P1:提示词预算与压缩

  • 为不同模型路由配置提示词/token 预算。
  • 根据预算自动选择 Detailed、Standard 或 Compact 胶囊。
  • 超出预算时依次删除推测项、可选特征和低优先级细节。
  • 用户锁定项、身份级特征和安全必要语境不得自动删除。
  • 转译层必须接收预算信息,避免先生成超长文本再粗暴截断。
  • 输出预算前后长度、删除内容和保留原因。
  • 预算压缩后重新进行一次轻量审核,防止上下文删除造成语义变化。

13. P1:参考图职责绑定

  • 定义 ReferenceImageBinding。
  • 每张参考图保存 role、use_for、do_not_inherit 和权重。
  • 角色参考图默认只继承身份、面部和发型。
  • 服装参考图默认禁止继承面部、体型、姿势、背景和画风。
  • 根据素材权重决定图片参考保留或降级为文字胶囊。
  • 超过模型参考图上限时给出确定性的降级顺序。
  • 为不同适配器实现职责与原生参数映射。
  • 不支持职责参数的模型自动追加明确的英文文本约束。

14. P1:API 与前端

  • 素材详情接口返回 RawAnalysis、NormalizedAssetProfile 和三档 Generation Capsule。
  • 素材详情增加“原始识别 / 标准属性 / 生图胶囊”页签。
  • 支持逐项修改属性、置信度、来源类型、槽位、层级和锁定状态。
  • 素材卡展示类别、槽位、层级和确认状态。
  • 增加按颜色、材质、槽位、层级、置信度筛选。
  • 角色衣橱支持设置优先级、锁定和可叠戴。
  • 角色拼装页增加槽位与层级视图。
  • 生图前显示冲突、自动解决方案和忽略项。
  • 提供最终提示词、负向提示词、参考图职责和路由决策预览。
  • 设置页增加提示词转译模型卡片和模板配置。
  • 设置页增加用户授权、入口授权和转译总开关。
  • 设置页增加普通生图路由、NSFW 生图路由和审核模型路由。
  • 设置页明确显示“成人内容可自动路由;恐怖与高危暴力内容始终禁止”的固定策略。
  • 设置页明确展示禁止内容不会被分流生成。
  • 聊天命令支持查看本次转译、审核和路由摘要,但默认不泄露内部规则细节。
  • 高风险或不确定内容提供用户确认交互。

15. P1:数据库、迁移与隐私

  • 第一阶段继续使用 material metadata 保存三层素材结构,避免立即大改表结构。
  • 为旧素材增加惰性迁移器。
  • 为提示词转译、审核和路由决策定义版本化记录结构。
  • 明确原始提示词、转译提示词和审核结果的保留时间。
  • 日志界面默认脱敏高风险原文。
  • 数据导出允许用户选择是否包含原始提示词和审核记录。
  • 数据备份包含素材 Schema 与胶囊版本。
  • 统计查询需求稳定后再评估独立 JSON 字段或子表。

16. P1:测试队列

  • 视觉模型合法三层结构返回测试。
  • 缺字段、错误字段类型、非 JSON 和超长响应测试。
  • 置信度 0.60/0.80 边界测试。
  • observed/inferred 分流测试。
  • 三档胶囊生成和旧素材 Legacy Capsule 测试。
  • 同义词标准化测试。
  • 连衣裙与上下装冲突测试。
  • 外套与内搭合法叠穿测试。
  • 同槽位配饰冲突与允许叠戴测试。
  • 用户锁定覆盖自动权重测试。
  • 中文转英文语义保持测试。
  • 中英文混合输入和专有名词锁定测试。
  • 转译模型超时、失败、空返回和格式错误测试。
  • 合规语义规范化不改变核心需求测试。
  • 禁止内容不能通过改写进入生成路由测试。
  • safe、sensitive、adult_allowed、uncertain、violence_prohibited、terror_prohibited、prohibited 分级审核测试。
  • 成人内容权限、用户白名单和群白名单组合测试。
  • 允许的成人内容在全部权限命中后自动选择 NSFW 路由测试。
  • 恐怖主义内容直接拒绝、返回警告且不创建任务测试。
  • 高危暴力与极端血腥内容直接拒绝、返回警告且不创建任务测试。
  • 恐暴内容不能通过手动指定 NSFW 路由绕过审核测试。
  • NSFW 路由未配置时明确失败测试。
  • 普通供应商的网络、超时、额度、鉴权、参数和未知失败不会触发 NSFW 路由测试。
  • 普通供应商明确内容安全拒绝后会触发二次审核测试。
  • 二次审核为 adult_allowed 且权限全部通过时,普通模型失败后单次回退 NSFW 模型测试。
  • 二次审核为 uncertain、恐暴或其他禁止内容时不回退并按策略确认、拒绝或警告测试。
  • NSFW 回退失败后不循环重试、不继续切换其他模型测试。
  • 路由决策发生在成本检查和任务入队前测试。
  • 提示词预算压缩与压缩后二次审核测试。
  • 多参考图职责和数量上限测试。
  • 生成后图片审核、隔离和图库权限测试。
  • QQ、Telegram、Discord 和 Web 入口回归测试。
  • 快速角色、详细角色、单图和高清修复全链路回归测试。

17. P2:后续增强

  • 素材识别和标准化版本对比。
  • 批量重新标准化,不重新调用视觉模型。
  • 素材组合模板和角色常用套装。
  • 根据角色体型、季节、场景自动调整可见性权重。
  • 基于生成结果审核素材还原度。
  • 将还原度反馈到素材权重和胶囊档位选择。
  • 统计素材采用率、冲突率、降级率、转译采用率、审核命中率和路由分布。
  • 为支持 ControlNet、IP-Adapter、区域提示词和多参考权重的适配器增加高级映射。
  • 对不同模型建立提示词效果基准集和离线评测。

18. 推荐实施批次

批次 A:数据基础

  • 三层素材 DTO、Schema、识别保存、标准化和 Legacy Capsule。
  • 标准类别、身体槽位、穿着层级。

批次 B:素材编译核心

  • CompositionBuilder、权重计算、冲突解决和编译日志。
  • 接入衣橱、快速角色和详细角色流程。

批次 C:转译与审核

  • PromptTranslationService、用户授权和语义规范化。
  • PromptModerationService 与成人、恐怖、暴力及其他禁止内容分级结果。

批次 D:模型动态分流

  • 普通/NSFW 路由配置、权限检查和 GenerationRouteDecision。
  • 在成本检查、任务入队前完成路由决策。

批次 E:前端闭环

  • 素材三层详情、拼装预览、冲突操作、转译预览、审核提示和路由配置。

批次 F:生成后审核与全量回归

  • 图片审核、隔离、图库权限和跨聊天平台测试。

19. 完成定义

  • 任意已确认素材均具有可追溯 RawAnalysis、标准化档案和至少一份可用胶囊。
  • 多素材组合不再通过无规则字符串拼接完成。
  • 每次拼装都能解释素材保留、降级和忽略原因。
  • 用户授权后,中文需求可稳定转为保持原意的英文模型提示词。
  • 规范化层不会隐藏禁止内容或绕过安全审核。
  • 每次生成前都有可审计的内容风险结果和模型路由决策。
  • 只有管理员配置、用户权限和审核结果同时允许时,成人内容才会自动进入 NSFW 路由。
  • 恐怖主义、高危暴力和极端血腥内容直接拒绝并警告,且不会创建生成任务。
  • 禁止内容不会进入普通或 NSFW 生图模型。
  • 生成后图片在返回聊天端和进入图库前完成相应审核。
  • 所有旧素材、旧工作流和现有前端功能保持兼容。
  • 后端、前端、数据库迁移及聊天平台测试全部通过。

20. 实施完成记录

  • 批次 A:三层素材 DTO/Schema、完整视觉结构保存、置信度规则、Legacy Capsule、标准类别、身体槽位和穿着层级。
  • 批次 B:CompositionBuilder、语义权重、用户锁定、冲突解决、预算压缩、参考图职责和详细工作流素材编译。
  • 批次 C:PromptTranslationService、用户授权、原文回退、PromptSemanticNormalizer、PromptModerationService 和恐暴禁止策略。
  • 批次 D:GenerationRouteDecision、普通/NSFW 动态路由、供应商失败分类、内容安全拒绝二次审核和单次 NSFW 回退。
  • 批次 E:设置页提示词治理卡片、发送前预览、素材三层详情/编辑/历史、语义筛选、套装模板与拼装预览。
  • 批次 F:生成后图片审核、单次自动再生成、隔离图库、管理员复核、聊天入口权限和成人独立白名单。
  • 数据与隐私:惰性迁移、批量重新标准化、Schema 版本备份、提示词/审核记录可选导出和日志脱敏记录。
  • 后续增强:套装模板、场景/季节/可见槽位权重、素材还原度反馈、统计 API、参考图方言映射和离线基准工具。
  • 后端回归:420 passed、1 skipped、31 subtests passed。
  • 前端验证:plugin-page 与 standalone-web 两套 Vite 生产构建通过。

主要新增入口:

  • POST prompts/governance-preview
  • GET materials/analytics
  • POST materials/renormalize-batch
  • POST materials/{material_id}/renormalize
  • GET/POST profiles/{profile_id}/wardrobe-templates
  • POST profiles/{profile_id}/wardrobe-templates/{template_id}/apply
  • POST images/{image_id}/moderation-review

说明:上方原始清单保留为需求追溯底稿;本节为最终实施状态,以自动化测试和生产构建结果为验收依据。