From b49e74e3ebfaa8bd16735766be224e1ce37b1a9f Mon Sep 17 00:00:00 2001 From: Bufan Deng <178316470@qq.com> Date: Wed, 14 Oct 2026 18:03:39 +0800 Subject: [PATCH] docs: index validation criteria by evaluator method --- ARCHITECTURE.md | 2 +- README.md | 2 +- README.zh-CN.md | 2 +- docs/assets/architecture.svg | 62 ++++++++++++++++++------------ docs/assets/architecture.zh-CN.svg | 62 ++++++++++++++++++------------ docs/evaluator-pipeline.md | 14 +++++++ docs/evaluator-pipeline.zh-CN.md | 14 +++++++ 7 files changed, 107 insertions(+), 51 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 0af6305..4d27966 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -8,7 +8,7 @@ The core package is provider-neutral. A multimodal host such as Codex or Claude ## Processing model -Processing pipeline with deterministic repair-grid checks, visual review of every primary asset, manifest export gates, optional transparency review, and PNG plus layered PSD delivery +Processing pipeline and validation catalog grouped by method, dimension, and keywords: repair-grid integrity, primary visual consistency, manifest gates, transparency checks, and PSD delivery constraints ### Scan diff --git a/README.md b/README.md index 4e9b092..4a77889 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ ultrasplit evaluate output/task/manifest.json --visual-verdict pass ## Architecture -Processing pipeline with deterministic repair-grid checks, visual review of every primary asset, manifest export gates, optional transparency review, and PNG plus layered PSD delivery +Processing pipeline and validation catalog grouped by method, dimension, and keywords: repair-grid integrity, primary visual consistency, manifest gates, transparency checks, and PSD delivery constraints Every run writes a schema-v3 manifest with exact source coordinates, route evidence, provenance, approval state, bounded repair attempts, evaluation status, and absolute delivery paths. See [ARCHITECTURE.md](ARCHITECTURE.md). diff --git a/README.zh-CN.md b/README.zh-CN.md index a6f5ea5..267cd14 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -129,7 +129,7 @@ ultrasplit evaluate output/task/manifest.json --visual-verdict pass ## 架构 -不规则素材图经过修复宫格确定性检查、主资产视觉审核和 manifest 导出门控后，交付图片与分层 PSD；另含可选透明版本审核和审批后修复路径 +按方法、维度和关键词归类的评估管线：修复宫格完整性、主资产视觉一致性、manifest 门控、透明版本检查与 PSD 交付约束 每次运行都会写入 schema v3 的 `manifest.json`，记录准确的源图坐标、路由依据、来源追踪、批准状态、有界修复次数、评估结果和绝对访问路径。完整设计见 [ARCHITECTURE.md](ARCHITECTURE.md)。 diff --git a/docs/assets/architecture.svg b/docs/assets/architecture.svg index 3f2b3ae..a2e7b7e 100644 --- a/docs/assets/architecture.svg +++ b/docs/assets/architecture.svg @@ -1,6 +1,6 @@ - + UltraSplitter processing model - An irregular asset sheet passes through deterministic scanning, host-led semantic planning, source-pixel routing, primary visual review, and delivery as named images, layered PSD pages, and a provenance manifest. Incomplete subjects may enter an approval-gated reconstruction path. Transparent variants use a separate optional review gate. + An irregular asset sheet passes through deterministic scanning, semantic planning, source-pixel routing, and primary visual review. A validation catalog groups repair-grid checks, host visual review, manifest gates, alpha review, and PSD delivery constraints by method, dimension, and keywords. Outputs include named images, layered PSD pages, and provenance. @@ -43,8 +43,8 @@ - - + + ULTRASPLITTER / PROCESSING MODEL From mixed sheet to traceable delivery @@ -226,25 +226,39 @@ Paths, routes + review state Recorded in the schema-v3 manifest. - - - VALIDATION METHODS / THREE DISTINCT EVIDENCE LAYERS - - DETERMINISTIC / REPAIR GRID - Resolution · occupied count · background consistency - Edge contact · safe margin · duplicate shapes - VISUAL / ALL PRIMARY ASSETS - Identity · pose · silhouette · color - Material · ornament · absence of redesign - MANIFEST / EXPORT GATE - Schema v3 · triage · approval · retry limit - Visual verdict must pass before PSD export - AUTOMATED CHECKS FLAG MEASURABLE DEFECTS; VISUAL REVIEW CHECKS IDENTITY; THE MANIFEST GATE CONTROLS PSD EXPORT. + + + VALIDATION / METHOD → DIMENSION → KEYWORDS + + DETERMINISTIC CHECK + Quantity & grid integrity + ≥512 px/cell · expected = occupied + background · edge · ≥8% margin + possible duplicates* + HOST VISUAL REVIEW + Inventory & visual consistency + count · no missing/extra assets + identity · pose · silhouette + color · material · no redesign + MANIFEST GATE + Workflow eligibility + Schema v3 · triage · approval + attempts ≤2 · visual = pass + ALPHA CHECK + REVIEW + Transparent-variant quality + real alpha · transparent background + foreground · edge · ≥8% margin + holes · white · black · checkerboard + PSD EXPORT + Delivery integrity + native pixels · ≤30,000 px/side + pages · tiles · manifest paths + * REPAIR-GRID METRICS APPLY TO GENERATED GRIDS; POSSIBLE DUPLICATES ARE FLAGGED FOR REVIEW. SEMANTIC IDENTITY REQUIRES HOST VISUAL REVIEW. - SOURCE PIXELS - - APPROVAL-GATED RECONSTRUCTION - - OPTIONAL ALPHA REVIEW - + SOURCE PIXELS + + APPROVAL-GATED RECONSTRUCTION + + OPTIONAL ALPHA REVIEW + diff --git a/docs/assets/architecture.zh-CN.svg b/docs/assets/architecture.zh-CN.svg index 19ca5dd..731746e 100644 --- a/docs/assets/architecture.zh-CN.svg +++ b/docs/assets/architecture.zh-CN.svg @@ -1,6 +1,6 @@ - + UltraSplitter 处理流程 - 不规则素材图经过确定性扫描、主体规划、原像素路由和主视觉审核，最终交付命名图片、分层 PSD 与来源清单。主体不完整时，可进入经批准的修复流程。透明版本另设可选审核。 + 不规则素材图经过确定性扫描、主体规划、原像素路由和主视觉审核。校验目录按方法、维度和关键词归类修复宫格检查、主体视觉审查、manifest 门控、透明版本审核和 PSD 交付约束。 @@ -43,8 +43,8 @@ - - + + ULTRASPLITTER / 处理流程 从混合素材图到可追溯交付 @@ -226,25 +226,39 @@ 路径、处理方式与审核状态 记录于 schema-v3 manifest。 - - - 校验方法 / 三个不同的证据层 - - 确定性检查 / 修复宫格 - 分辨率 · 有效格数 · 背景一致性 - 触边 · 安全留白 · 重复图形 - 视觉审核 / 全部主资产 - 身份 · 姿态 · 轮廓 · 色彩 - 材质 · 装饰 · 是否发生重设计 - Manifest 门控 / 导出条件 - Schema v3 · 分诊 · 批准 · 重试上限 - 主视觉结论通过后才导出 PSD - 自动检查定位可量化缺陷；视觉审核判断主体一致性；manifest 门控决定能否导出 PSD。 + + + 校验方法 / 方法 → 维度 → 关键词 + + 确定性检查 + 数量与宫格完整性 + 每格 ≥512 px · 预期=有效格数 + 背景 · 触边 · 留白 ≥8% + 疑似重复图形* + 宿主视觉审查 + 清单完整性与视觉一致性 + 数量 · 不漏项 · 不多项 + 身份 · 姿态 · 轮廓 + 颜色 · 材质 · 装饰 · 不重设计 + Manifest 门控 + 流程交付资格 + Schema v3 · 分诊 · 批准 + 重试 ≤2 次 · 视觉结论 pass + Alpha 校验与审查 + 透明版本质量 + 真实 Alpha · 透明背景 + 前景 · 触边 · 留白 ≥8% + 内部空洞 · 白底 · 黑底 · 棋盘格 + PSD 导出 + 交付完整性 + 原像素 · 单边 ≤30,000 px + 分卷 · 切块 · manifest 路径 + * 宫格量化检查只针对生成式修复；疑似重复项会标记供复核。主体语义一致性仍须视觉审查。 - 原图像素 - - 经批准的图像修复 - - 可选透明版本审核 - + 原图像素 + + 经批准的图像修复 + + 可选透明版本审核 + diff --git a/docs/evaluator-pipeline.md b/docs/evaluator-pipeline.md index ede6020..2701760 100644 --- a/docs/evaluator-pipeline.md +++ b/docs/evaluator-pipeline.md @@ -42,4 +42,18 @@ flowchart TD A4 --> A1 ``` +## Evaluation criteria and evaluator index + +Use the same three-part description for each category: **method → dimension → keywords**. The evaluator index links to the implementation; host visual review is not performed by Python and `evaluate_manifest()` only consumes its verdict. + +| Method | Dimension | Keywords / criteria | Evaluator method (source index) | +|---|---|---|---| +| Deterministic grid check | Repair-grid integrity | Resolution (at least 512 px per cell); expected vs. occupied count; background consistency; edge contact; safe margin (at least 8%); possible duplicate shapes are reported for review. | [`evaluate_grid()`](../src/ultrasplitter/evaluator.py#L27) | +| Host multimodal visual review | Inventory and visual consistency | Reconcile the confirmed inventory with delivered assets (no missing or extra subjects); compare each asset with the source for identity, pose, silhouette, color, material, ornament, and no redesign. | Host review; [`evaluate_manifest()`](../src/ultrasplitter/evaluator.py#L115) consumes `visual_verdict` but does not inspect images. | +| Manifest gate | Workflow eligibility | Schema version 3; completed semantic triage; approved conflict groups; repair-attempt limit; required visual verdict is `pass`. | [`require_v3()`](../src/ultrasplitter/contracts.py#L48), [`evaluate_manifest()`](../src/ultrasplitter/evaluator.py#L115) | +| Transparent-variant check and review | Alpha integrity and compositing quality | Real alpha channel; transparent background; non-empty foreground; no edge contact; at least 8% safe margin; interior transparency is flagged for visual review; preview on white, black, and checkerboard. | [`inspect_transparent_candidate()`](../src/ultrasplitter/transparency.py#L60), [`apply_transparent_verdict()`](../src/ultrasplitter/transparency.py#L199); primary success is enforced by [`evaluate_manifest()`](../src/ultrasplitter/evaluator.py#L115). | +| PSD export | Delivery integrity | Native-pixel layers; pages stay within 30,000 px per side; oversized assets are tiled; paths and export details are recorded in the manifest. | [`export_layered_psd()`](../src/ultrasplitter/layered_psd.py#L119) | + +Deterministic checks apply to generated repair grids; they do not certify semantic identity. Possible duplicate shapes are reported as evidence and still require review. The visual verdict comes from the host review, while the manifest gate controls whether that verdict and other workflow state permit delivery. + `ultrasplit run` creates and routes the manifest; it does not itself pass the evaluation gate. The CLI `evaluate` command, or repair ingestion after a successful grid check, calls `evaluate_manifest` and can reach PSD export. diff --git a/docs/evaluator-pipeline.zh-CN.md b/docs/evaluator-pipeline.zh-CN.md index 906607c..3f1874d 100644 --- a/docs/evaluator-pipeline.zh-CN.md +++ b/docs/evaluator-pipeline.zh-CN.md @@ -42,4 +42,18 @@ flowchart TD A4 --> A1 ``` +## 评估标准与 evaluator 方法索引 + +各类标准统一按 **方法 → 维度 → 关键词** 表述。方法索引链接到对应实现；主资产的视觉审查由宿主模型完成，不在 Python evaluator 中执行；`evaluate_manifest()` 只接收并处理视觉结论。 + +| 方法 | 维度 | 关键词 / 标准 | 对应 evaluator 方法（源码索引） | +|---|---|---|---| +| 确定性宫格检查 | 修复宫格完整性 | 分辨率（每格至少 512 px）；预期格数与有效格数一致；背景一致性；触边；安全留白（至少 8%）；可能重复的图形会被标记供复核。 | [`evaluate_grid()`](../src/ultrasplitter/evaluator.py#L27) | +| 宿主多模态视觉审查 | 清单完整性与视觉一致性 | 将已确认清单与交付素材核对（不漏项、不多项）；逐件对照源图检查身份、姿态、轮廓、颜色、材质、装饰，以及是否发生重设计。 | 宿主完成审查；[`evaluate_manifest()`](../src/ultrasplitter/evaluator.py#L115) 接收 `visual_verdict`，不负责看图。 | +| Manifest 门控 | 流程交付资格 | schema 版本为 3；语义分诊完成；冲突组已批准；修复次数未耗尽；要求视觉结论为 `pass`。 | [`require_v3()`](../src/ultrasplitter/contracts.py#L48)、[`evaluate_manifest()`](../src/ultrasplitter/evaluator.py#L115) | +| 透明版本校验与审查 | Alpha 完整性与合成质量 | 存在真实 Alpha 通道；背景透明；前景非空；主体不触边；安全留白至少 8%；内部透明区域会标记并要求视觉复核；在白底、黑底、棋盘格上预览。 | [`inspect_transparent_candidate()`](../src/ultrasplitter/transparency.py#L60)、[`apply_transparent_verdict()`](../src/ultrasplitter/transparency.py#L199)；[`evaluate_manifest()`](../src/ultrasplitter/evaluator.py#L115) 负责主资产通过后的状态门控。 | +| PSD 导出 | 交付完整性 | 图层保留原像素；每份画布单边不超过 30,000 px；超大素材切块；路径和导出信息写入 manifest。 | [`export_layered_psd()`](../src/ultrasplitter/layered_psd.py#L119) | + +确定性检查针对生成式修复宫格，不代表语义身份正确。可能重复的图形只作为检查证据返回，仍需复核。视觉结论由宿主审查给出；manifest 门控结合该结论和流程状态决定能否交付。 + `ultrasplit run` 负责生成并路由 manifest，本身不会通过审核门控。CLI 的 `evaluate` 命令，或修复宫格检查通过后的导入流程，会调用 `evaluate_manifest` 并可能进入 PSD 导出。