diff --git a/_conf_schema.json b/_conf_schema.json index bd0b4fa..e5cfe24 100644 --- a/_conf_schema.json +++ b/_conf_schema.json @@ -2977,6 +2977,18 @@ "default": false, "invisible": true }, + "enable_p5_structured_reference_assets": { + "description": "Legacy flat config: 启用 Q5 受管结构化参考素材", + "type": "bool", + "default": false, + "invisible": true + }, + "photo_structured_reference_assets": { + "description": "Legacy flat config: Q5 受管结构化参考素材配置", + "type": "list", + "default": [], + "invisible": true + }, "enable_group_nsfw_private_fallback": { "description": "Legacy flat config: 群聊成图安全审核与私聊回退", "type": "bool", @@ -9055,6 +9067,27 @@ "enable_photo_text_action": true } }, + "enable_p5_structured_reference_assets": { + "description": "Q5 受管结构化参考素材(多图)", + "type": "bool", + "hint": "默认关闭。开启后,只有管理员放入插件数据目录 photo_reference_assets 并登记文件相对路径、SHA-256、职责的本地图片,才可能作为生图参考输入。旧参考图库、聊天图、引用图、URL 不会被升级为多图输入。", + "default": false, + "condition": { + "enable_photo_text_action": true, + "enable_photo_reference_image": true + } + }, + "photo_structured_reference_assets": { + "description": "Q5 受管素材清单", + "type": "list", + "hint": "仅管理员配置。每项为 JSON 对象:id、role(identity/outfit/pose/scene/style)、file(photo_reference_assets 下的相对路径)、sha256,及可选的 outfit_lock_default、continuation_match、new_topic_enabled、edit_enabled。面板只显示校验状态,不显示路径或哈希。", + "default": [], + "condition": { + "enable_photo_text_action": true, + "enable_photo_reference_image": true, + "enable_p5_structured_reference_assets": true + } + }, "enable_group_nsfw_private_fallback": { "description": "群聊成图安全审核与私聊回退", "type": "bool", diff --git a/main.py b/main.py index ef18645..db46ae5 100644 --- a/main.py +++ b/main.py @@ -1739,6 +1739,17 @@ class PrivateCompanionPlugin( self.photo_reference_library = [ line.strip() for line in str(raw_reference_library or "").splitlines() if line.strip() ][:24] + self.enable_p5_structured_reference_assets = self._cfg_bool( + c, + "enable_p5_structured_reference_assets", + False, + ) + raw_structured_assets = self._cfg_raw(c, "photo_structured_reference_assets", []) + self.photo_structured_reference_assets = ( + [dict(item) for item in raw_structured_assets if isinstance(item, dict)][:16] + if isinstance(raw_structured_assets, list) + else [] + ) self.comfyui_photo_wait_seconds = self._cfg_int(c, "comfyui_photo_wait_seconds", 90, 5, 600) self.photo_generation_backend = self._cfg_str(c, "photo_generation_backend", "auto", "auto").strip().lower() if self.photo_generation_backend not in {"auto", "comfyui", "sdgen", "external", "tool_call"}: diff --git a/page_api.py b/page_api.py index df46f7f..0435c13 100644 --- a/page_api.py +++ b/page_api.py @@ -29,6 +29,7 @@ from .constants import DEFAULT_DAILY_PLAN_ITEMS, PAGE_FONT_NAMES, PAGE_THEME_NAM from .config_migration import _ensure_config_parent_dir from .diagnostic_envelope import DIAGNOSTIC_ENVELOPE_VERSION, diagnostic_test_id, normalize_diagnostic_result from .helpers import _flat_get, _normalize_timezone_name, _path_text, _redact_outbound_secrets, _safe_int, _set_into_config, _set_today_key_timezone, _strip_internal_message_blocks, _text_looks_garbled, _text_similarity, _today_key +from .reference_asset_gate import ReferenceAssetGate from .page_api_qzone import PrivateCompanionPageApiQzoneMixin from .page_api_users_groups import PrivateCompanionPageApiUsersGroupsMixin from .planning import evaluate_daily_plan_quality, generate_daily_plan, generate_detail_enhancement @@ -1179,6 +1180,19 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio payload = f"{kind}\0{source}".encode("utf-8", errors="ignore") return hashlib.sha256(payload).hexdigest()[:24] + def _q5_structured_reference_asset_projection(self) -> dict[str, Any]: + enabled = bool(getattr(self.plugin, "enable_p5_structured_reference_assets", False)) + backend = self._single_line(getattr(self.plugin, "photo_generation_backend", "auto"), 30).lower() + capacity = 4 if backend == "comfyui" else (1 if backend == "external" else 0) + gate = ReferenceAssetGate(getattr(self.plugin, "data_dir", "")) + projection = gate.public_projection( + getattr(self.plugin, "photo_structured_reference_assets", []), + backend_capacity=capacity, + ) + projection["enabled"] = enabled + projection["backend"] = backend or "auto" + return projection + def _photo_reference_page_items(self) -> list[dict[str, Any]]: entries: list[dict[str, Any]] = [] persona_source = _path_text( @@ -1296,6 +1310,7 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio "items": library, "total": len(library), "available": sum(1 for item in library if item.get("available")), + "structured_assets": self._q5_structured_reference_asset_projection(), }) except Exception as exc: logger.error(f"[PrivateCompanionPage] 获取参考图库失败: {exc}", exc_info=True) @@ -11644,6 +11659,7 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio "enable_poke_action", "enable_voice_action", "enable_photo_reference_image", + "enable_p5_structured_reference_assets", "inject_passive_states", "enable_passive_state_delta_injection", "enable_cycle_state", @@ -13046,6 +13062,7 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio "quote_target_strategy", "enable_photo_text_action", "enable_photo_reference_image", + "enable_p5_structured_reference_assets", "photo_action_max_daily", "photo_generation_backend", "custom_photo_tool_name", @@ -15014,6 +15031,9 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio reference_enabled = self._config_get("enable_photo_reference_image") if reference_enabled not in ("", None): self.plugin.enable_photo_reference_image = self._normalize_bool_value(reference_enabled) + structured_enabled = self._config_get("enable_p5_structured_reference_assets") + if structured_enabled not in ("", None): + self.plugin.enable_p5_structured_reference_assets = self._normalize_bool_value(structured_enabled) enabled_backup = self._config_get("enable_backup_external_image_api") if enabled_backup not in ("", None): self.plugin.enable_backup_external_image_api = self._normalize_bool_value(enabled_backup) @@ -15606,6 +15626,7 @@ class PrivateCompanionPageApi(PrivateCompanionPageApiQzoneMixin, PrivateCompanio "COMFYUI_TEXT2IMG_WORKFLOW_NAME", "COMFYUI_SELFIE_WORKFLOW_NAME", "enable_photo_reference_image", + "enable_p5_structured_reference_assets", "photo_persona_reference_image_path", "photo_reference_library", "enable_daily_outfit_photo", diff --git a/pages/陪伴面板/app.css b/pages/陪伴面板/app.css index 7b8921d..81c527b 100644 --- a/pages/陪伴面板/app.css +++ b/pages/陪伴面板/app.css @@ -18766,6 +18766,65 @@ textarea { color: var(--ink); } +.structured-reference-status { + display: grid; + gap: 12px; + margin: 2px 16px 16px; + padding: 16px; + border: 1px solid color-mix(in srgb, var(--accent) 25%, var(--line-soft)); + border-radius: 12px; + background: color-mix(in srgb, var(--accent-soft) 52%, #fff 48%); +} + +.structured-reference-status > header { + display: flex; + align-items: start; + justify-content: space-between; + gap: 12px; +} + +.structured-reference-status header span:first-child, +.structured-reference-status header small, +.structured-reference-note, +.structured-reference-empty { + color: var(--muted); +} + +.structured-reference-status h3 { + margin: 3px 0; + font-size: 15px; +} + +.structured-reference-backend { + padding: 4px 8px; + border-radius: 999px; + background: #fff; + color: var(--accent); + font: 600 12px/1 var(--font-mono, monospace); +} + +.structured-reference-assets { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); + gap: 8px; +} + +.structured-reference-assets > div { + display: grid; + gap: 3px; + padding: 9px 10px; + border-radius: 10px; + background: #fff; +} + +.structured-reference-assets b { overflow-wrap: anywhere; } +.structured-reference-assets span { color: var(--muted); font-size: 12px; } +.structured-reference-assets small { font-size: 12px; } +.structured-reference-assets .is-ok { color: var(--green, #23845b); } +.structured-reference-assets .is-error { color: var(--red, #c34b57); } +.structured-reference-note, +.structured-reference-empty { margin: 0; font-size: 12px; } + .photo-reference-head-actions { display: flex; flex-wrap: wrap; diff --git a/pages/陪伴面板/app.js b/pages/陪伴面板/app.js index 7a5b306..d846a3a 100644 --- a/pages/陪伴面板/app.js +++ b/pages/陪伴面板/app.js @@ -5943,6 +5943,7 @@ const setupGuideAdvancedItems = { { key: "external_image_download_proxy", type: "text", label: "在线结果下载代理", placeholder: "http://127.0.0.1:7890", showWhen: (draft) => photoSettingVisibleForValues("external_image_download_proxy", draft) }, { key: "external_image_download_use_environment_proxy", type: "bool", label: "结果下载使用系统代理", description: "仅影响在线生图结果 URL 的下载。", showWhen: (draft) => photoSettingVisibleForValues("external_image_download_use_environment_proxy", draft) }, { key: "enable_photo_reference_image", type: "bool", kind: "feature", label: "启用参考图一致性", description: "可选。开启后自拍/头像/角色表情包会自动使用人设参考图或今日穿搭图保持外观;不需要稳定外观时可以关闭。", showWhen: (draft) => photoSettingVisibleForValues("enable_photo_reference_image", draft) }, + { key: "enable_p5_structured_reference_assets", type: "bool", kind: "feature", label: "受管结构化参考素材(Q5)", description: "默认关闭。只允许管理员登记且哈希校验通过的本地图片进入受控参考输入;聊天图、引用图、URL 和旧图库不会自动获得多图权限。", showWhen: (draft) => photoSettingVisibleForValues("enable_p5_structured_reference_assets", draft) }, { key: "photo_persona_reference_image_path", type: "text", label: "人设参考图路径/URL", placeholder: "C:\\path\\role.png 或 https://...", description: "仅在参考图一致性开启时使用;本地路径和图片 URL 都可以。", showWhen: (draft) => photoSettingVisibleForValues("photo_persona_reference_image_path", draft) }, { key: "photo_reference_library", type: "textarea", label: "带注释的参考图库", placeholder: "C:\\path\\home.png || 居家服,在家、卧室、睡前使用\nC:\\path\\outdoor.png || 外出服,逛街、通勤时使用", description: "一行一张。Bot 会根据最终场景选择一张;今日穿搭图只在场景确实匹配时参与选择。", showWhen: (draft) => photoSettingVisibleForValues("photo_reference_library", draft) }, { key: "enable_group_nsfw_private_fallback", type: "bool", kind: "setting", label: "群聊成图安全审核与私聊回退", description: "可选。安全图正常发群;任何不适合群内发送、无法确认或审核不可用的图都只尝试私聊原请求者。没有可用识图模型时不会群发。" }, @@ -20647,6 +20648,9 @@ function photoSettingVisibleForValues(settingKey, values = {}) { return onlineBackends.has(backend); } if (settingKey === "enable_photo_reference_image") return backend !== "sdgen"; + if (settingKey === "enable_p5_structured_reference_assets") { + return backend !== "sdgen" && enabled("enable_photo_reference_image"); + } if (["photo_persona_reference_image_path", "photo_reference_library"].includes(settingKey)) { return backend !== "sdgen" && enabled("enable_photo_reference_image"); } @@ -22115,6 +22119,41 @@ function photoReferenceManagerCard(item, index) { `; } +function structuredReferenceAssetStatusHtml() { + const structured = state.photoReferenceLibraryStatus?.structured_assets || {}; + const items = Array.isArray(structured.items) ? structured.items : []; + const enabled = Boolean(structured.enabled); + const capacity = Number.isFinite(Number(structured.backend_capacity)) ? Number(structured.backend_capacity) : 0; + const backend = String(structured.backend || "auto"); + const summary = enabled + ? `${items.filter((item) => item.valid).length} / ${items.length} 项通过校验 · 当前后端容量 ${capacity}` + : "功能关闭;不会向任何生图后端提交受管素材"; + return ` +
+
+
+ Q5 受管素材 +

结构化参考输入状态

+ ${escapeHtml(summary)} +
+ ${escapeHtml(backend)} +
+ ${items.length ? ` +
+ ${items.map((item) => ` +
+ ${escapeHtml(String(item.id || "未命名素材"))} + ${escapeHtml(String(item.role || "未知职责"))} + ${escapeHtml(item.valid ? "校验通过" : String(item.status || "校验失败"))} +
+ `).join("")} +
+ ` : `

尚未登记受管素材。请在设置中登记受管目录内的文件与 SHA-256。

`} +

此处不会显示文件路径、URL、SHA-256 或一次性授权票据。

+
+ `; +} + function photoReferenceManagerPageHtml(open) { const items = photoReferenceManagerItems(); const personaSource = currentPhotoPersonaReferenceValue(); @@ -22139,6 +22178,8 @@ function photoReferenceManagerPageHtml(open) { + ${structuredReferenceAssetStatusHtml()} +
默认身份锚点 diff --git a/proactive_message.py b/proactive_message.py index d0e4061..f519262 100644 --- a/proactive_message.py +++ b/proactive_message.py @@ -109,6 +109,12 @@ from .dreaming import ( recent_diary_tags, weighted_unique_fragment_sample, ) +from .reference_asset_gate import ( + MAX_INPUT_ASSETS, + ReferenceAssetGate, + ReferenceAssetPlan, + ReferenceAssetTicket, +) from .helpers import ( _date_key, _normalize_outbound_punctuation_flow, @@ -9952,6 +9958,33 @@ Output: ) reference_image_path = _path_text(reference_candidate.get("path"), 1000) + structured_reference_gate, structured_reference_plan, structured_reference_status = ( + self._q5_prepare_structured_reference_plan( + generation_id=trace_id, + workflow_kind=workflow_kind, + prompt_text=original_prompt_text or base_prompt, + reference_candidate=reference_candidate, + ) + ) + if structured_reference_plan and structured_reference_plan.primary_asset: + primary = structured_reference_plan.primary_asset + reference_image_path = str(primary.path) + reference_candidate = self._normalize_photo_reference_candidate_metadata( + { + "id": primary.asset_id, + "path": str(primary.path), + "source": "q5_managed_asset", + "kind": "managed_asset", + "note": "管理员登记并校验的受管身份参考素材", + "reference_roles": [item.role for item in structured_reference_plan.assets], + "outfit_lock_default": any( + item.role == "outfit" and item.outfit_lock_default + for item in structured_reference_plan.assets + ), + "metadata_source": "q5_reference_asset_gate", + } + ) + wardrobe = self._resolve_photo_wardrobe_decision( workflow_kind=workflow_kind, prompt_text=original_prompt_text or base_prompt, @@ -10045,6 +10078,13 @@ Output: preset_section=preset_section, continuity_section=continuity_section, ) + if structured_reference_plan and structured_reference_plan.prompt_constraint: + prompt_sections["managed_reference_constraints"] = structured_reference_plan.prompt_constraint + prompt_text = self._photo_prompt_clip( + f"{prompt_text}\n\n{structured_reference_plan.prompt_constraint}", + 3600, + preserve_tail=True, + ) conflicts = self._detect_photo_prompt_conflicts(prompt_text, wardrobe) if conflicts: prompt_text = self._append_photo_prompt_conflict_resolution(prompt_text, wardrobe, conflicts) @@ -10086,6 +10126,7 @@ Output: logger.info( "[PrivateCompanion] 生图开始: trace=%s session=%s kind=%s presets=%s prompt_chars=%s prompt_hash=%s prompt_debug=%s " "reference=%s reference_exists=%s reference_id=%s reference_kind=%s reference_roles=%s " + "q5_reference_assets=%s q5_reference_status=%s " "wardrobe_mode=%s wardrobe_category=%s outfit_locked=%s daily_outfit_removed=%s continuity_reference=%s " "image_size=%s prompt_preview_chars=%s prompt_preview=%s %s", trace_id, @@ -10100,6 +10141,8 @@ Output: _single_line(reference_candidate.get("id"), 60) or "-", _single_line(reference_candidate.get("kind"), 40) or "-", ",".join(reference_candidate.get("reference_roles") or []) or "-", + ",".join(item.asset_id for item in structured_reference_plan.assets) if structured_reference_plan else "-", + structured_reference_status, wardrobe.mode or "none", wardrobe.category or "none", wardrobe.lock_outfit, @@ -10179,6 +10222,30 @@ Output: ) return backend, image_path, note + def single_image_reference_for_backend(backend_name: str) -> str: + if structured_reference_plan is None: + return reference_image_path + paths, status = self._q5_single_image_ticket_paths( + structured_reference_gate, + structured_reference_plan, + generation_id=trace_id, + backend=backend_name, + ) + if paths: + return paths[0] + logger.warning( + "[PrivateCompanion] Q5 单图参考素材未获授权: trace=%s backend=%s status=%s", + trace_id, + _single_line(backend_name, 30), + status, + ) + return "" + + def comfyui_reference_ticket() -> ReferenceAssetTicket | None: + if structured_reference_gate is None or structured_reference_plan is None: + return None + return structured_reference_gate.issue(structured_reference_plan, backend="comfyui") + if reference_image_path and not reference_exists: return finish("参考图", "", f"参考图路径不可用或文件不存在:{_single_line(reference_image_path, 160)}") @@ -10196,6 +10263,10 @@ Output: prompt_text, session_key=session_key, reference_image_path=reference_image_path, + reference_asset_gate=structured_reference_gate, + reference_asset_ticket=comfyui_reference_ticket(), + generation_id=trace_id, + structured_reference_count=len(structured_reference_plan.assets) if structured_reference_plan else 0, ) return finish( "ComfyUI", @@ -10206,7 +10277,7 @@ Output: if preferred == "sdgen": if not self._sdgen_photo_available(): return finish("SDGen", "", "SDGen 插件不可用或未配置") - if reference_image_path: + if reference_image_path and structured_reference_plan is None: return finish("SDGen", "", "SDGen 后端不支持参考图输入,请改用在线参考图接口或 ComfyUI images=1 自拍工作流") busy_state = self._local_photo_generation_busy_state(force_refresh=True) if busy_state: @@ -10223,7 +10294,7 @@ Output: prompt_text, session_key=session_key, workflow_kind=workflow_kind, - reference_image_path=reference_image_path, + reference_image_path="" if structured_reference_plan else reference_image_path, image_size=image_size, ) if image_path: @@ -10243,7 +10314,7 @@ Output: image_path, note = await self._run_external_photo_generation( prompt_text, session_key=session_key, - reference_image_path=reference_image_path, + reference_image_path=single_image_reference_for_backend("external"), image_size=image_size, ) if image_path: @@ -10264,7 +10335,7 @@ Output: image_path, note = await self._run_external_photo_generation( prompt_text, session_key=session_key, - reference_image_path=reference_image_path, + reference_image_path=single_image_reference_for_backend("external"), image_size=image_size, ) if image_path: @@ -10292,6 +10363,10 @@ Output: prompt_text, session_key=session_key, reference_image_path=reference_image_path, + reference_asset_gate=structured_reference_gate, + reference_asset_ticket=comfyui_reference_ticket(), + generation_id=trace_id, + structured_reference_count=len(structured_reference_plan.assets) if structured_reference_plan else 0, ) if image_path: return finish( @@ -10308,7 +10383,7 @@ Output: else: comfyui_note = "ComfyUI 后端不可用或未配置" logger.info("[PrivateCompanion] 生图后端跳过: trace=%s backend=comfyui note=%s", trace_id, comfyui_note) - if reference_image_path: + if reference_image_path and structured_reference_plan is None: sdgen_note = "本次需要参考图,已跳过不支持参考图输入的 SDGen 纯文生图" logger.info("[PrivateCompanion] 生图后端跳过: trace=%s backend=sdgen note=%s", trace_id, sdgen_note) elif self._sdgen_photo_available(): @@ -10570,6 +10645,80 @@ Output: return "其他", "保持统一审美风格,自然生活感,避免默认写实照片风格" return "真实", "真实摄影风格,像手机随手拍到的生活照片,光线自然,细节可信" + def _q5_structured_reference_assets_enabled(self) -> bool: + return bool(getattr(self, "enable_p5_structured_reference_assets", False)) + + def _q5_structured_reference_generation_mode( + self, + workflow_kind: str, + prompt_text: str, + reference_candidate: dict[str, Any], + ) -> str: + kind = _single_line(workflow_kind, 40).lower() + if kind in {"edit", "改图", "修图", "重绘"}: + return "edit" + if reference_candidate.get("kind") == "recent_sent_photo" or re.search( + r"续拍|继续拍|接着拍|再来一张|换个姿势|换个表情|same scene|continue the photo", + str(prompt_text or ""), + flags=re.I, + ): + return "continuation" + return "new_topic" + + def _q5_prepare_structured_reference_plan( + self, + *, + generation_id: str, + workflow_kind: str, + prompt_text: str, + reference_candidate: dict[str, Any], + ) -> tuple[ReferenceAssetGate | None, ReferenceAssetPlan | None, str]: + if not self._q5_structured_reference_assets_enabled(): + return None, None, "disabled" + # A user-provided or quoted edit image remains a legacy single-image flow. + # It is never promoted into this managed multi-image sink. + if _single_line(reference_candidate.get("kind"), 40).lower() in {"source", "explicit"}: + return None, None, "legacy_explicit_reference" + gate = ReferenceAssetGate(self.data_dir) + mode = self._q5_structured_reference_generation_mode( + workflow_kind, + prompt_text, + reference_candidate, + ) + plan, status = gate.plan( + getattr(self, "photo_structured_reference_assets", []), + generation_id=generation_id, + mode=mode, + ) + if not plan: + logger.info( + "[PrivateCompanion] Q5 受管参考素材未进入图片输入汇: trace=%s status=%s", + _single_line(generation_id, 80), + status, + ) + return gate, None, status + return gate, plan, "ok" + + @staticmethod + def _q5_single_image_ticket_paths( + gate: ReferenceAssetGate | None, + plan: ReferenceAssetPlan | None, + *, + generation_id: str, + backend: str, + ) -> tuple[list[str], str]: + if gate is None or plan is None: + return [], "not_structured" + ticket = gate.issue(plan, backend=backend) + if ticket is None: + return [], "ticket_issue_failed" + return gate.consume( + ticket, + generation_id=generation_id, + backend=backend, + capacity=1, + ) + def _photo_persona_reference_image_path(self) -> str: raw = _path_text(getattr(self, "photo_persona_reference_image_path", ""), 1000) if not raw: @@ -11323,6 +11472,10 @@ Output: session_key: str, reference_image_path: str = "", image_size: str = "", + reference_asset_gate: ReferenceAssetGate | None = None, + reference_asset_ticket: ReferenceAssetTicket | None = None, + generation_id: str = "", + structured_reference_count: int = 0, ) -> tuple[str, str]: module = self._get_comfyui_module() if module is None: @@ -11335,12 +11488,42 @@ Output: workflow_dir = module._get_workflow_dir() reference_image_path = _path_text(reference_image_path, 1000) use_reference_image = bool(reference_image_path and os.path.isfile(reference_image_path)) + use_structured_assets = bool( + reference_asset_gate is not None + and reference_asset_ticket is not None + and generation_id + and structured_reference_count > 0 + ) if reference_image_path and not use_reference_image: return "", "ComfyUI 提交前参考图已不可用,已停止纯文工作流回退" workflow_file = "" text_count = 1 image_count = 0 - if use_reference_image: + if use_structured_assets: + for requested_count in range(min(MAX_INPUT_ASSETS, structured_reference_count), 0, -1): + workflow_file = module.find_workflow_file( + workflow_name, + 1, + requested_count, + 0, + workflow_dir, + ) + image_count = requested_count if workflow_file else 0 + if not workflow_file: + workflow_file, text_count, image_count = self._find_photo_workflow_with_text_count( + module, + workflow_dir, + workflow_name, + image_count=requested_count, + ) + if workflow_file: + break + if not workflow_file: + return "", ( + f"Q5 受管参考素材已就绪,但 ComfyUI 工作流 {workflow_name} 不接收图片输入;" + "请配置 images=N(N>=1)的工作流,避免降级为未使用受管素材的纯文生图" + ) + elif use_reference_image: workflow_file = module.find_workflow_file( workflow_name, 1, @@ -11397,9 +11580,20 @@ Output: ) workflow = module.ComfyUIWorkflow(server_ip, client_id) workflow.load_workflow_api(workflow_file) - input_images = [reference_image_path] if image_count > 0 and use_reference_image else [] + input_images: list[str] = [] reference_note = "" - if input_images: + if use_structured_assets: + input_images, ticket_status = reference_asset_gate.consume( + reference_asset_ticket, + generation_id=generation_id, + backend="comfyui", + capacity=image_count, + ) + if ticket_status != "ok" or not input_images: + return "", f"Q5 受管参考素材票据无效:{ticket_status}" + reference_note = f";已使用 {len(input_images)} 张受管参考素材" + elif image_count > 0 and use_reference_image: + input_images = [reference_image_path] reference_note = ";已使用本地人设参考图" elif use_reference_image: return "", ( diff --git a/reference_asset_gate.py b/reference_asset_gate.py new file mode 100644 index 0000000..b3ed955 --- /dev/null +++ b/reference_asset_gate.py @@ -0,0 +1,245 @@ +"""Conservative local gate for structured image-reference assets (REQ-021 Q5). + +This module intentionally does not import the cross-plugin P5 attestation +contract. A structured reference asset is a local, administrator-registered +file only; it grants a one-shot image-model input for one generation and +nothing else. +""" +from __future__ import annotations + +import hashlib +import re +import secrets +import time +from dataclasses import dataclass +from pathlib import Path +from typing import Any + + +CONTRACT_NAME = "ops.p5.reference_asset_sink.v1" +ROLE_ORDER = ("identity", "outfit", "pose", "scene", "style") +ALLOWED_EXTENSIONS = frozenset({".png", ".jpg", ".jpeg", ".webp"}) +MAX_ASSET_BYTES = 20 * 1024 * 1024 +MAX_INPUT_ASSETS = 4 +TICKET_TTL_SECONDS = 90 +_ASSET_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$") + + +@dataclass(frozen=True) +class ManagedReferenceAsset: + asset_id: str + role: str + path: Path + prompt_label: str + outfit_lock_default: bool + continuation_match: bool + new_topic_enabled: bool + edit_enabled: bool + + +@dataclass(frozen=True) +class ReferenceAssetPlan: + generation_id: str + mode: str + assets: tuple[ManagedReferenceAsset, ...] + prompt_constraint: str + + @property + def primary_asset(self) -> ManagedReferenceAsset | None: + return next((item for item in self.assets if item.role == "identity"), None) + + def public_projection(self) -> dict[str, Any]: + return { + "contract": CONTRACT_NAME, + "enabled": True, + "mode": self.mode, + "asset_ids": [item.asset_id for item in self.assets], + "roles": [item.role for item in self.assets], + "total": len(self.assets), + } + + +@dataclass(frozen=True) +class ReferenceAssetTicket: + """Opaque in-memory capability. It has no serializer by design.""" + + nonce: str + + +class ReferenceAssetGate: + """Validate managed assets and mediate their only allowed sink.""" + + def __init__(self, data_dir: str | Path, *, now: Any = time.time) -> None: + self._root = (Path(data_dir) / "photo_reference_assets").resolve() + self._now = now + self._tickets: dict[str, dict[str, Any]] = {} + + @property + def root(self) -> Path: + return self._root + + @staticmethod + def _text(value: Any, limit: int = 160) -> str: + return " ".join(str(value or "").split())[:limit] + + @staticmethod + def _bool(value: Any, default: bool = False) -> bool: + if isinstance(value, bool): + return value + if value is None or str(value).strip() == "": + return default + return str(value).strip().lower() in {"1", "true", "yes", "on", "enabled"} + + def _resolve_registered_path(self, value: Any) -> Path | None: + raw = self._text(value, 240).replace("\\", "/") + if not raw or raw.startswith(("/", "//")) or ":" in raw or ".." in raw.split("/"): + return None + try: + candidate = (self._root / raw).resolve() + candidate.relative_to(self._root) + except (OSError, ValueError): + return None + return candidate + + @staticmethod + def _sha256(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as stream: + for block in iter(lambda: stream.read(1024 * 1024), b""): + digest.update(block) + return digest.hexdigest() + + def validate_entry(self, raw: Any) -> tuple[ManagedReferenceAsset | None, str]: + if not isinstance(raw, dict): + return None, "entry_not_object" + asset_id = self._text(raw.get("id") or raw.get("asset_id"), 80) + role = self._text(raw.get("role"), 24).lower() + digest = self._text(raw.get("sha256"), 80).lower() + path = self._resolve_registered_path(raw.get("file") or raw.get("relative_path")) + if not _ASSET_ID_RE.fullmatch(asset_id): + return None, "invalid_id" + if role not in ROLE_ORDER: + return None, "invalid_role" + if not re.fullmatch(r"[0-9a-f]{64}", digest): + return None, "invalid_hash" + if path is None: + return None, "outside_managed_directory" + try: + if not path.is_file(): + return None, "file_missing" + if path.suffix.lower() not in ALLOWED_EXTENSIONS: + return None, "unsupported_extension" + if path.stat().st_size > MAX_ASSET_BYTES: + return None, "file_too_large" + if not secrets.compare_digest(self._sha256(path), digest): + return None, "hash_mismatch" + except OSError: + return None, "file_unreadable" + return ManagedReferenceAsset( + asset_id=asset_id, + role=role, + path=path, + prompt_label=self._text(raw.get("label"), 80), + outfit_lock_default=self._bool(raw.get("outfit_lock_default"), False), + continuation_match=self._bool(raw.get("continuation_match"), False), + new_topic_enabled=self._bool(raw.get("new_topic_enabled"), True), + edit_enabled=self._bool(raw.get("edit_enabled"), False), + ), "ok" + + def inspect(self, entries: Any) -> dict[str, Any]: + items = entries if isinstance(entries, list) else [] + result: list[dict[str, Any]] = [] + valid: dict[str, ManagedReferenceAsset] = {} + seen_roles: set[str] = set() + for raw in items[:16]: + asset, status = self.validate_entry(raw) + raw_id = self._text(raw.get("id") if isinstance(raw, dict) else "", 80) + raw_role = self._text(raw.get("role") if isinstance(raw, dict) else "", 24).lower() + asset_id = raw_id if _ASSET_ID_RE.fullmatch(raw_id) else "" + role = raw_role if raw_role in ROLE_ORDER else "" + if asset and asset.role in seen_roles: + asset, status = None, "duplicate_role" + if asset: + seen_roles.add(asset.role) + valid[asset.role] = asset + asset_id, role = asset.asset_id, asset.role + result.append({"id": asset_id, "role": role, "status": status, "valid": status == "ok"}) + return {"items": result, "valid_by_role": valid} + + def plan(self, entries: Any, *, generation_id: str, mode: str) -> tuple[ReferenceAssetPlan | None, str]: + mode = self._text(mode, 24).lower() + if mode not in {"continuation", "edit", "new_topic"}: + return None, "invalid_mode" + generation_id = self._text(generation_id, 120) + if not generation_id: + return None, "missing_generation_id" + inspected = self.inspect(entries) + by_role: dict[str, ManagedReferenceAsset] = inspected["valid_by_role"] + identity = by_role.get("identity") + if identity is None: + return None, "missing_verified_identity" + selected: list[ManagedReferenceAsset] = [identity] + outfit = by_role.get("outfit") + if outfit and (outfit.outfit_lock_default if mode == "continuation" else mode == "new_topic"): + selected.append(outfit) + for role in ("pose", "scene"): + asset = by_role.get(role) + if asset and ((mode == "continuation" and asset.continuation_match) or (mode == "new_topic" and asset.new_topic_enabled) or (mode == "edit" and asset.edit_enabled)): + selected.append(asset) + style = by_role.get("style") + if style and ((mode == "continuation" and style.continuation_match) or (mode == "new_topic" and style.new_topic_enabled) or (mode == "edit" and style.edit_enabled)): + selected.append(style) + selected.sort(key=lambda item: ROLE_ORDER.index(item.role)) + selected = selected[:MAX_INPUT_ASSETS] + constraints = [item for item in selected if item.role != "identity"] + prompt_constraint = "" + if constraints: + names = ", ".join(item.role for item in constraints) + prompt_constraint = f"Managed visual constraints: keep the approved {names} reference consistent." + return ReferenceAssetPlan(generation_id=generation_id, mode=mode, assets=tuple(selected), prompt_constraint=prompt_constraint), "ok" + + def issue(self, plan: ReferenceAssetPlan, *, backend: str) -> ReferenceAssetTicket | None: + if not isinstance(plan, ReferenceAssetPlan) or not plan.primary_asset: + return None + nonce = secrets.token_urlsafe(24) + ticket = ReferenceAssetTicket(nonce=nonce) + self._tickets[nonce] = { + "ticket": ticket, + "plan": plan, + "backend": self._text(backend, 24).lower(), + "expires_at": float(self._now()) + TICKET_TTL_SECONDS, + "consumed": False, + } + return ticket + + def consume( + self, + ticket: ReferenceAssetTicket, + *, + generation_id: str, + backend: str, + capacity: int, + ) -> tuple[list[str], str]: + record = self._tickets.get(getattr(ticket, "nonce", "")) + if not record or record.get("ticket") is not ticket: + return [], "unknown_ticket" + if record["consumed"] or float(self._now()) > float(record["expires_at"]): + return [], "expired_or_consumed_ticket" + plan: ReferenceAssetPlan = record["plan"] + if generation_id != plan.generation_id or self._text(backend, 24).lower() != record["backend"]: + return [], "scope_mismatch" + if capacity <= 0: + return [], "invalid_capacity" + record["consumed"] = True + paths = [str(item.path) for item in plan.assets[:max(1, min(capacity, MAX_INPUT_ASSETS))]] + return paths, "ok" + + def public_projection(self, entries: Any, *, backend_capacity: int) -> dict[str, Any]: + inspected = self.inspect(entries) + return { + "contract": CONTRACT_NAME, + "managed_directory": "photo_reference_assets", + "items": inspected["items"], + "backend_capacity": max(0, min(int(backend_capacity or 0), MAX_INPUT_ASSETS)), + "max_assets": MAX_INPUT_ASSETS, + } diff --git a/tests/test_req021_q5_reference_asset_gate.py b/tests/test_req021_q5_reference_asset_gate.py new file mode 100644 index 0000000..7cdc1bb --- /dev/null +++ b/tests/test_req021_q5_reference_asset_gate.py @@ -0,0 +1,132 @@ +from __future__ import annotations + +import hashlib +import sys +import tempfile +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from reference_asset_gate import ( # noqa: E402 + CONTRACT_NAME, + MAX_INPUT_ASSETS, + ReferenceAssetGate, +) + + +class ReferenceAssetGateTests(unittest.TestCase): + def setUp(self) -> None: + self.tempdir = tempfile.TemporaryDirectory() + self.data_dir = Path(self.tempdir.name) + self.asset_dir = self.data_dir / "photo_reference_assets" + self.asset_dir.mkdir() + self.gate = ReferenceAssetGate(self.data_dir, now=lambda: 1000.0) + + def tearDown(self) -> None: + self.tempdir.cleanup() + + def _entry(self, name: str, role: str, **extra: object) -> dict[str, object]: + path = self.asset_dir / name + path.write_bytes(f"image:{name}".encode("utf-8")) + payload: dict[str, object] = { + "id": name.rsplit(".", 1)[0], + "role": role, + "file": name, + "sha256": hashlib.sha256(path.read_bytes()).hexdigest(), + } + payload.update(extra) + return payload + + def test_only_registered_local_hashed_assets_are_accepted(self) -> None: + valid = self._entry("identity.png", "identity") + asset, status = self.gate.validate_entry(valid) + self.assertEqual("ok", status) + self.assertEqual("identity", asset.role if asset else "") + + for source in ( + {**valid, "file": "../identity.png"}, + {**valid, "file": "C:/outside.png"}, + {**valid, "file": "https://example.invalid/identity.png"}, + {**valid, "sha256": "0" * 64}, + {**valid, "role": "source"}, + ): + rejected, rejected_status = self.gate.validate_entry(source) + self.assertIsNone(rejected) + self.assertNotEqual("ok", rejected_status) + + def test_roles_are_deduplicated_and_new_topic_is_stably_ordered(self) -> None: + entries = [ + self._entry("style.png", "style"), + self._entry("scene.png", "scene"), + self._entry("identity.png", "identity"), + self._entry("outfit.png", "outfit", outfit_lock_default=True), + self._entry("pose.png", "pose"), + self._entry("identity-duplicate.png", "identity"), + ] + plan, status = self.gate.plan(entries, generation_id="gen-1", mode="new_topic") + self.assertEqual("ok", status) + self.assertIsNotNone(plan) + self.assertEqual(["identity", "outfit", "pose", "scene"], [item.role for item in plan.assets]) + self.assertLessEqual(len(plan.assets), MAX_INPUT_ASSETS) + + def test_continuation_and_edit_only_add_explicitly_enabled_roles(self) -> None: + entries = [ + self._entry("identity.png", "identity"), + self._entry("outfit.png", "outfit", outfit_lock_default=True), + self._entry("pose.png", "pose", continuation_match=True), + self._entry("scene.png", "scene", continuation_match=False, edit_enabled=True), + ] + continuation, status = self.gate.plan(entries, generation_id="continue", mode="continuation") + self.assertEqual("ok", status) + self.assertEqual(["identity", "outfit", "pose"], [item.role for item in continuation.assets]) + + edit, status = self.gate.plan(entries, generation_id="edit", mode="edit") + self.assertEqual("ok", status) + self.assertEqual(["identity", "scene"], [item.role for item in edit.assets]) + + def test_ticket_is_opaque_one_shot_and_generation_backend_bound(self) -> None: + entries = [self._entry("identity.png", "identity")] + plan, status = self.gate.plan(entries, generation_id="gen-2", mode="new_topic") + self.assertEqual("ok", status) + ticket = self.gate.issue(plan, backend="comfyui") + self.assertIsNotNone(ticket) + denied, denied_status = self.gate.consume(ticket, generation_id="other", backend="comfyui", capacity=1) + self.assertEqual([], denied) + self.assertEqual("scope_mismatch", denied_status) + + paths, consume_status = self.gate.consume(ticket, generation_id="gen-2", backend="comfyui", capacity=1) + self.assertEqual("ok", consume_status) + self.assertEqual(1, len(paths)) + reused, reused_status = self.gate.consume(ticket, generation_id="gen-2", backend="comfyui", capacity=1) + self.assertEqual([], reused) + self.assertEqual("expired_or_consumed_ticket", reused_status) + + def test_projection_does_not_disclose_path_or_hash(self) -> None: + entry = self._entry("identity.png", "identity") + projection = self.gate.public_projection( + [entry, {"id": "C:/sensitive-path.png", "role": "identity", "file": "identity.png", "sha256": entry["sha256"]}], + backend_capacity=4, + ) + encoded = repr(projection) + self.assertEqual(CONTRACT_NAME, projection["contract"]) + self.assertNotIn(str(self.asset_dir), encoded) + self.assertNotIn(str(entry["sha256"]), encoded) + self.assertNotIn("sensitive-path", encoded) + self.assertEqual("identity", projection["items"][0]["role"]) + + def test_runtime_and_panel_have_only_q5_gate_call_sites(self) -> None: + proactive = (ROOT / "proactive_message.py").read_text(encoding="utf-8") + page_api = (ROOT / "page_api.py").read_text(encoding="utf-8") + frontend = (ROOT / "pages" / "陪伴面板" / "app.js").read_text(encoding="utf-8") + self.assertIn("reference_asset_ticket", proactive) + self.assertIn("structured_reference_count", proactive) + self.assertIn("_q5_structured_reference_asset_projection", page_api) + self.assertIn("structuredReferenceAssetStatusHtml", frontend) + + +if __name__ == "__main__": + unittest.main()