feat(image): gate structured reference assets

这个提交存在于:
YokiiroBW 2026-08-01 04:31:38 +08:00
父节点 46ac0a717d
当前提交 2cf690cdd5
共有 8 个文件被更改,包括 744 次插入 和 8 次删除

查看文件

@ -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",

11
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"}:

查看文件

@ -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",

查看文件

@ -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;

查看文件

@ -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 `
<section class="structured-reference-status" aria-labelledby="structuredReferenceTitle">
<header>
<div>
<span>Q5 受管素材</span>
<h3 id="structuredReferenceTitle">结构化参考输入状态</h3>
<small>${escapeHtml(summary)}</small>
</div>
<span class="structured-reference-backend">${escapeHtml(backend)}</span>
</header>
${items.length ? `
<div class="structured-reference-assets">
${items.map((item) => `
<div>
<b>${escapeHtml(String(item.id || "未命名素材"))}</b>
<span>${escapeHtml(String(item.role || "未知职责"))}</span>
<small class="${item.valid ? "is-ok" : "is-error"}">${escapeHtml(item.valid ? "校验通过" : String(item.status || "校验失败"))}</small>
</div>
`).join("")}
</div>
` : `<p class="structured-reference-empty">尚未登记受管素材。请在设置中登记受管目录内的文件与 SHA-256。</p>`}
<p class="structured-reference-note">此处不会显示文件路径、URL、SHA-256 或一次性授权票据。</p>
</section>
`;
}
function photoReferenceManagerPageHtml(open) {
const items = photoReferenceManagerItems();
const personaSource = currentPhotoPersonaReferenceValue();
@ -22139,6 +22178,8 @@ function photoReferenceManagerPageHtml(open) {
</div>
</header>
${structuredReferenceAssetStatusHtml()}
<section class="photo-reference-persona" aria-labelledby="photoReferencePersonaTitle">
<div>
<span>默认身份锚点</span>

查看文件

@ -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 "", (

245
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,
}

查看文件

@ -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()