feat(portrait-clearance): 肖像排查 - 增加画布插件与本机检测链路

This commit is contained in:
QAyong authored and ddCat committed 2026-08-26 15:23:19 +08:00
1 parent 86fc3fda2f
commit 9bc5512140
54 files changed
+6832 -60

No files matched your search

+244
View File
@@ -0,0 +1,244 @@
/**
* 肖像可识别性排查的跨组件合同。
*
* 画布只持久化这里的紧凑节点状态;图片、embedding、候选列表和完整模型响应
* 必须留在 Local Runtime 任务目录中。
*/
export const PORTRAIT_CLEARANCE_SCHEMA_VERSION = 1 as const;
export const PORTRAIT_CLEARANCE_PLUGIN_ID = "portrait-clearance" as const;
export const PORTRAIT_CLEARANCE_NODE_TYPE = "portrait-clearance" as const;
export type PortraitRiskLevel =
| "high"
| "medium"
| "low_to_medium"
| "low"
| "unable_to_determine";
export type PortraitClearanceMode = "direct-compare" | "network-search";
export type PortraitClearanceAnalysisMode = "local-plus-vision" | "local-only";
export type PortraitClearanceDedupMode = "phash" | "arcface";
export type PortraitClearanceInputRole = "query" | "reference" | "candidate";
export type PortraitClearanceInputBinding = {
nodeId: string;
role: PortraitClearanceInputRole;
};
export type PortraitClearanceModelPolicy =
| { mode: "project-default" }
| { mode: "pinned"; modelRef: string };
export type PortraitClearanceTaskStatus =
| "queued"
| "running"
| "waiting_model"
| "partial"
| "completed"
| "failed"
| "cancelled";
export type PortraitClearanceTaskStage =
| "validating-inputs"
| "checking-model-resources"
| "preparing-query"
| "searching"
| "downloading-candidates"
| "deduplicating"
| "local-comparing"
| "waiting-for-model"
| "model-comparing"
| "building-report"
| "done";
export type PortraitClearanceNodeState = {
schemaVersion: typeof PORTRAIT_CLEARANCE_SCHEMA_VERSION;
mode: PortraitClearanceMode;
analysisMode: PortraitClearanceAnalysisMode;
modelPolicy: PortraitClearanceModelPolicy;
inputBindings: PortraitClearanceInputBinding[];
settings: {
maxCandidates: number;
searchScrolls: number;
dedupMode: PortraitClearanceDedupMode;
modelConcurrency: number;
showBrowserForDebug: boolean;
};
activeTaskId?: string;
task?: {
status: PortraitClearanceTaskStatus;
stage: PortraitClearanceTaskStage;
progress: number;
processedCandidates: number;
totalCandidates?: number;
errorCode?: string;
errorMessage?: string;
updatedAt: string;
};
lastResult?: {
taskId: string;
highestRisk: PortraitRiskLevel;
riskCounts: Partial<Record<PortraitRiskLevel, number>>;
candidateCount: number;
comparedCount: number;
modelRef?: string;
completedAt: string;
detailsAvailable: boolean;
};
};
export type PortraitClearanceSettings = PortraitClearanceNodeState["settings"];
export type PortraitImageQuality = {
width: number;
height: number;
sharpness: number;
brightness: number;
contrast: number;
grade: "good" | "usable" | "poor";
};
export type PortraitLocalPrecheck = {
qualityA: PortraitImageQuality;
qualityB: PortraitImageQuality;
facesA: number;
facesB: number;
selectedFaceA?: { bbox: [number, number, number, number]; detScore: number; areaRatio: number };
selectedFaceB?: { bbox: [number, number, number, number]; detScore: number; areaRatio: number };
faceSimilarity?: number;
ssim: number;
colorHistogramCorrelation: number;
canExtractEmbedding: boolean;
reliabilityIssues: string[];
};
export type PortraitFeatureKey =
| "face_shape"
| "facial_layout"
| "eyes_brows"
| "nose_mouth"
| "hair_hairline"
| "distinctive_features";
export type PortraitVisionComparison = {
imageAType: "realistic" | "stylized";
imageBType: "realistic" | "stylized";
analysisPath: "A" | "B";
status: "success" | "unable_to_determine";
riskLevel: PortraitRiskLevel;
overallSimilarity: number;
featureComparison: Record<PortraitFeatureKey, {
similarity: "high" | "medium" | "low" | "none";
note: string;
}>;
basis: string[];
limitations: string[];
modificationSuggestions: string[];
insightfaceFusionNote: string;
manualReviewRecommended: boolean;
};
export type PortraitPairResult = {
id: string;
queryImageId: string;
comparisonImageId: string;
candidateId?: string;
source: "connected-reference" | "connected-candidate" | "baidu";
status: "success" | "partial" | "failed";
riskLevel: PortraitRiskLevel;
overallSimilarity?: number;
analysisPath: "A" | "B" | "unable";
localPrecheck: PortraitLocalPrecheck;
visionComparison?: PortraitVisionComparison;
basis: string[];
limitations: string[];
error?: { code: string; message: string; retryable: boolean };
};
export type PortraitCandidate = {
id: string;
originalRank: number;
title: string;
imageArtifactId: string;
imageUrl?: string;
sourcePageUrl?: string;
sourceDomain?: string;
source: "connected" | "baidu";
byteSize: number;
width?: number;
height?: number;
dedupGroupId?: string;
resultId?: string;
};
export type PortraitClearanceResult = {
schemaVersion: typeof PORTRAIT_CLEARANCE_SCHEMA_VERSION;
taskId: string;
ownerScopeHash: string;
projectId: string;
nodeId: string;
mode: PortraitClearanceMode;
analysisMode: PortraitClearanceAnalysisMode;
modelRef?: string;
createdAt: string;
completedAt?: string;
highestRisk: PortraitRiskLevel;
riskCounts: Partial<Record<PortraitRiskLevel, number>>;
localPrecheck?: PortraitLocalPrecheck;
candidates: PortraitCandidate[];
pairs: PortraitPairResult[];
limitations: string[];
manualReviewRecommended: boolean;
};
export const DEFAULT_PORTRAIT_CLEARANCE_SETTINGS: PortraitClearanceNodeState["settings"] = {
maxCandidates: 30,
searchScrolls: 5,
dedupMode: "phash",
modelConcurrency: 2,
showBrowserForDebug: false,
};
export function createDefaultPortraitClearanceState(): PortraitClearanceNodeState {
return {
schemaVersion: PORTRAIT_CLEARANCE_SCHEMA_VERSION,
mode: "direct-compare",
analysisMode: "local-plus-vision",
modelPolicy: { mode: "project-default" },
inputBindings: [],
settings: { ...DEFAULT_PORTRAIT_CLEARANCE_SETTINGS },
};
}
export const PORTRAIT_RISK_ORDER: readonly PortraitRiskLevel[] = ["high", "medium", "low_to_medium", "low", "unable_to_determine"];
export const PORTRAIT_RISK_LABELS: Record<PortraitRiskLevel, string> = {
high: "高风险",
medium: "中风险",
low_to_medium: "中低风险",
low: "低风险",
unable_to_determine: "无法判断",
};
export const PORTRAIT_TASK_STAGE_LABELS: Record<PortraitClearanceTaskStage, string> = {
"validating-inputs": "校验输入",
"checking-model-resources": "检查本地模型",
"preparing-query": "准备查询图",
searching: "网络搜图",
"downloading-candidates": "采集候选",
deduplicating: "候选去重",
"local-comparing": "本地比对",
"waiting-for-model": "等待视觉模型",
"model-comparing": "视觉模型分析",
"building-report": "生成报告",
done: "已完成",
};
export function isPortraitClearanceTerminalStatus(status?: PortraitClearanceTaskStatus) {
return status === "partial" || status === "completed" || status === "failed" || status === "cancelled";
}
export function comparePortraitRisk(left: PortraitRiskLevel, right: PortraitRiskLevel) {
return PORTRAIT_RISK_ORDER.indexOf(left) - PORTRAIT_RISK_ORDER.indexOf(right);
}
@@ -0,0 +1,76 @@
import { CanvasNodeType, type CanvasConnection, type CanvasNodeData } from "@/types/canvas";
import type { PortraitClearanceInputBinding, PortraitClearanceInputRole, PortraitClearanceMode } from "./contracts";
/**
* 连接顺序只作为旧画布的迁移兜底。已有 role 永远优先保留,避免渲染顺序变化
* 导致 query/reference 被静默交换。
*/
export function reconcilePortraitClearanceInputBindings(
mode: PortraitClearanceMode,
clearanceNodeId: string,
connections: readonly CanvasConnection[],
nodes: readonly CanvasNodeData[],
existing: readonly PortraitClearanceInputBinding[] = [],
): PortraitClearanceInputBinding[] {
const nodeById = new Map(nodes.map((node) => [node.id, node]));
const connectedIds = connections
.filter((connection) => connection.toNodeId === clearanceNodeId)
.sort((left, right) => left.id.localeCompare(right.id))
.map((connection) => connection.fromNodeId)
.filter((nodeId, index, all) => all.indexOf(nodeId) === index)
.filter((nodeId) => {
const node = nodeById.get(nodeId);
return isPortraitImageInput(node);
});
const connected = new Set(connectedIds);
const result: PortraitClearanceInputBinding[] = [];
const usedRoles = new Set<PortraitClearanceInputRole>();
for (const binding of existing) {
if (!connected.has(binding.nodeId) || result.some((item) => item.nodeId === binding.nodeId)) continue;
const role = normalizeRole(mode, binding.role, usedRoles);
if (!role) continue;
result.push({ nodeId: binding.nodeId, role });
usedRoles.add(role);
}
for (const nodeId of connectedIds) {
if (result.some((item) => item.nodeId === nodeId)) continue;
const role = nextRole(mode, usedRoles);
if (!role) break;
result.push({ nodeId, role });
usedRoles.add(role);
}
return result;
}
export function swapPortraitClearanceDirectBindings(bindings: readonly PortraitClearanceInputBinding[]) {
return bindings.map((binding) => binding.role === "query"
? { ...binding, role: "reference" as const }
: binding.role === "reference"
? { ...binding, role: "query" as const }
: binding);
}
export function portraitInputBindingForRole(bindings: readonly PortraitClearanceInputBinding[], role: PortraitClearanceInputRole) {
return bindings.find((binding) => binding.role === role)?.nodeId;
}
function normalizeRole(mode: PortraitClearanceMode, role: PortraitClearanceInputRole, used: ReadonlySet<PortraitClearanceInputRole>) {
if (mode === "direct-compare" && role === "candidate") return nextRole(mode, used);
if (used.has(role)) return nextRole(mode, used);
return role;
}
function nextRole(mode: PortraitClearanceMode, used: ReadonlySet<PortraitClearanceInputRole>): PortraitClearanceInputRole | null {
if (!used.has("query")) return "query";
if (mode === "direct-compare" && !used.has("reference")) return "reference";
if (mode === "network-search") return "candidate";
return null;
}
export function isPortraitImageInput(node: CanvasNodeData | undefined) {
return Boolean(node && node.type === CanvasNodeType.Image && (node.metadata?.content || node.metadata?.storageKey));
}
+132
View File
@@ -0,0 +1,132 @@
import { modelDisplayName, selectableModelsByCapability, type AiConfig } from "@/stores/use-config-store";
import type { PortraitClearanceModelPolicy, PortraitRiskLevel } from "@/lib/portrait-clearance/contracts";
import type { ResponseFunctionTool, ResponseInputMessage, ToolResponseResult } from "@/services/api/image";
export type PortraitVisionFeatureKey = "face_shape" | "facial_layout" | "eyes_brows" | "nose_mouth" | "hair_hairline" | "distinctive_features";
export type PortraitVisionComparison = {
imageAType: "realistic" | "stylized";
imageBType: "realistic" | "stylized";
analysisPath: "A" | "B";
status: "success" | "unable_to_determine";
riskLevel: PortraitRiskLevel;
overallSimilarity: number;
featureComparison: Record<PortraitVisionFeatureKey, { similarity: "high" | "medium" | "low" | "none"; note: string }>;
basis: string[];
limitations: string[];
modificationSuggestions: string[];
insightfaceFusionNote: string;
manualReviewRecommended: boolean;
};
const FEATURE_KEYS: PortraitVisionFeatureKey[] = ["face_shape", "facial_layout", "eyes_brows", "nose_mouth", "hair_hairline", "distinctive_features"];
const SIMILARITIES = new Set(["high", "medium", "low", "none"]);
const RISKS = new Set<PortraitRiskLevel>(["high", "medium", "low_to_medium", "low", "unable_to_determine"]);
export const portraitVisionTool: ResponseFunctionTool = {
type: "function",
function: {
name: "submit_portrait_comparison",
description: "提交两张人物图片的结构化可识别性排查结果;不识别人名、不确认私人身份,也不作法律判断。",
strict: true,
parameters: {
type: "object",
additionalProperties: false,
required: ["imageAType", "imageBType", "analysisPath", "status", "riskLevel", "overallSimilarity", "featureComparison", "basis", "limitations", "modificationSuggestions", "insightfaceFusionNote", "manualReviewRecommended"],
properties: {
imageAType: { type: "string", enum: ["realistic", "stylized"] },
imageBType: { type: "string", enum: ["realistic", "stylized"] },
analysisPath: { type: "string", enum: ["A", "B"] },
status: { type: "string", enum: ["success", "unable_to_determine"] },
riskLevel: { type: "string", enum: ["high", "medium", "low_to_medium", "low", "unable_to_determine"] },
overallSimilarity: { type: "number", minimum: 0, maximum: 1 },
featureComparison: {
type: "object",
additionalProperties: false,
required: FEATURE_KEYS,
properties: Object.fromEntries(FEATURE_KEYS.map((key) => [key, { type: "object", additionalProperties: false, required: ["similarity", "note"], properties: { similarity: { type: "string", enum: ["high", "medium", "low", "none"] }, note: { type: "string", maxLength: 1000 } } }])),
},
basis: { type: "array", maxItems: 16, items: { type: "string", maxLength: 1000 } },
limitations: { type: "array", maxItems: 16, items: { type: "string", maxLength: 1000 } },
modificationSuggestions: { type: "array", maxItems: 16, items: { type: "string", maxLength: 1000 } },
insightfaceFusionNote: { type: "string", maxLength: 1000 },
manualReviewRecommended: { type: "boolean" },
},
},
},
};
export function portraitVisionModels(config: AiConfig) {
return selectableModelsByCapability(config, "text");
}
export function resolvePortraitVisionModel(config: AiConfig, policy: PortraitClearanceModelPolicy) {
const models = portraitVisionModels(config);
const preferred = policy.mode === "pinned" ? policy.modelRef : config.textModel || config.model;
return preferred && models.includes(preferred) ? preferred : policy.mode === "pinned" ? "" : models[0] || "";
}
export function portraitVisionModelError(config: AiConfig, policy: PortraitClearanceModelPolicy) {
if (!resolvePortraitVisionModel(config, policy)) return policy.mode === "pinned" ? "节点固定的视觉模型已失效,请重新选择" : "项目默认视觉模型不可用,请重新选择";
return "";
}
export function portraitVisionModelLabel(config: AiConfig, model: string) {
return model ? modelDisplayName(config, model) : "未选择";
}
export function portraitVisionMessages(input: { queryDataUrl: string; comparisonDataUrl: string; queryName: string; comparisonName: string; localPrecheck: unknown }): ResponseInputMessage[] {
return [
{
role: "system",
content: "你是影策中的肖像可识别性排查分析器。只做结构化视觉比较,不识别人名或私人身份,不输出确认同一人、确认侵权、绝对安全等确定性结论。两张均为写实人像时使用 Path A,任一张明显风格化时使用 Path B;请结合本地 ArcFace、检测和质量预检,但不要将本地 embedding 当作法律结论。对脸型、五官布局、眼眉、鼻口、发型发际线、标志性特征分别说明。若图片质量、多脸或风格差异使判断不可靠,返回 unable_to_determine 并说明限制。",
},
{
role: "user",
content: [
{ type: "text", text: `查询图:${input.queryName}\n参考/候选图:${input.comparisonName}\n本地预检(仅作辅助):${JSON.stringify(input.localPrecheck)}` },
{ type: "image_url", image_url: { url: input.queryDataUrl } },
{ type: "image_url", image_url: { url: input.comparisonDataUrl } },
],
},
];
}
export function parsePortraitVisionToolResponse(response: ToolResponseResult): PortraitVisionComparison {
const call = response.toolCalls.find((candidate) => candidate.function.name === "submit_portrait_comparison");
if (!call) throw new Error("portrait_vision_tool_missing");
let value: unknown;
try { value = JSON.parse(call.function.arguments); } catch { throw new Error("portrait_vision_result_invalid"); }
return parseVisionComparison(value);
}
export function parseVisionComparison(value: unknown): PortraitVisionComparison {
if (!isRecord(value) || !["realistic", "stylized"].includes(String(value.imageAType)) || !["realistic", "stylized"].includes(String(value.imageBType)) || !["A", "B"].includes(String(value.analysisPath)) || !["success", "unable_to_determine"].includes(String(value.status)) || !RISKS.has(value.riskLevel as PortraitRiskLevel) || typeof value.overallSimilarity !== "number" || !Number.isFinite(value.overallSimilarity) || value.overallSimilarity < 0 || value.overallSimilarity > 1 || !isRecord(value.featureComparison) || !Array.isArray(value.basis) || !Array.isArray(value.limitations) || !Array.isArray(value.modificationSuggestions) || typeof value.insightfaceFusionNote !== "string" || typeof value.manualReviewRecommended !== "boolean") throw new Error("portrait_vision_result_invalid");
const featureComparison = Object.fromEntries(FEATURE_KEYS.map((key) => {
const item = value.featureComparison[key];
if (!isRecord(item) || !SIMILARITIES.has(String(item.similarity)) || typeof item.note !== "string" || item.note.length > 1000) throw new Error("portrait_vision_result_invalid");
return [key, { similarity: item.similarity as "high" | "medium" | "low" | "none", note: item.note }];
})) as PortraitVisionComparison["featureComparison"];
return {
imageAType: value.imageAType as "realistic" | "stylized",
imageBType: value.imageBType as "realistic" | "stylized",
analysisPath: value.analysisPath as "A" | "B",
status: value.status as "success" | "unable_to_determine",
riskLevel: value.riskLevel as PortraitRiskLevel,
overallSimilarity: value.overallSimilarity,
featureComparison,
basis: boundedStrings(value.basis),
limitations: boundedStrings(value.limitations),
modificationSuggestions: boundedStrings(value.modificationSuggestions),
insightfaceFusionNote: value.insightfaceFusionNote,
manualReviewRecommended: value.manualReviewRecommended,
};
}
function boundedStrings(value: unknown) {
if (!Array.isArray(value) || value.length > 16 || value.some((item) => typeof item !== "string" || item.length === 0 || item.length > 1000)) throw new Error("portrait_vision_result_invalid");
return value as string[];
}
function isRecord(value: unknown): value is Record<string, any> {
return Boolean(value && typeof value === "object" && !Array.isArray(value));
}