Harden figure placeholder and table crop gates

Author: 917Dhj

.claude/worktrees/adoring-rubin-51fd84

@@ -0,0 +1 @@
+Subproject commit 6cf896712dced7a03844cc2925d0589e3db60c19

SKILL.md

@@ -133,7 +133,9 @@ Local-library-first rule (applies only when the Zotero check above succeeds):
 - High-quality notes should usually contain multiple meaningful `###` subheadings in the technical sections when the paper is non-trivial.
 - The note must include figure/table placeholders for all major visuals rather than silently skipping them.
 - Every kept figure/table placeholder must appear directly under the most relevant analytical section named by its `建议位置`; do not collect unresolved placeholders in catch-all sections such as `剩余图表占位` or `Remaining figures`.
+- Every kept figure/table placeholder must use the standard `> [!figure]` callout format with `建议位置`, `放置原因`, and `当前状态`; do not use ordinary paragraph markers such as `[图表占位 | Fig. 1]`, `图表占位：Table 2`, or `Figure Placeholder | Fig. 3`.
 - Real images may replace some placeholders, but only if they clearly match the corresponding paper figure/table.
+- When inserting a real image, prefer the `obsidian_embed` returned by `scripts/materialize_figure_asset.py`.
 - Figure captions in the note must preserve the original paper numbering such as `Fig. 1` or `Table 2`.
 - The note must pass a style gate: no mixed Chinese-English prose lines except stable proper nouns or citation metadata.
 - Style gate enforcement: when `lint_note.py` output contains `passes_style_gate: false`, fix the reported issues and re-run lint. Keep fixing and re-running until lint passes — multiple rounds are normal and expected. Do not decide that any failure is an acceptable exception — proper nouns, math formulas, and citation metadata are not automatic exemptions. Only escalate to the user if the same failures appear unchanged across multiple rounds with no reduction, indicating the model is unable to make further progress independently.

references/figure-placement.md

@@ -71,11 +71,15 @@ Fail closed when visual usability is weak: keep the placeholder instead of inser
 Reject candidates that are:
 - caption-only crops
 - tables with no visible table body
+- table crops contaminated by running prose or another Figure/Table caption
 - large text, title-page, or abstract crops masquerading as figures
 - crops where the visual body is tiny relative to the crop
 
 ## Placeholder Requirements
 
+Every kept placeholder in the final note must use the standard `[!figure]` callout format.
+Do not use ordinary paragraph markers such as `[图表占位 | Fig. 1]`, `图表占位：Table 2`, or `Figure Placeholder | Fig. 3`.
+
 Each placeholder should include:
 - figure or table id
 - a short label
@@ -102,6 +106,7 @@ The placeholder text should be stable and explicit:
 If a real image is inserted:
 - keep the original paper identifier, for example `Fig. 2` or `Table 1`
 - do not renumber it according to note order
+- prefer the `obsidian_embed` returned by `scripts/materialize_figure_asset.py`
 - if the extracted image is only a subpanel or partial crop, say so explicitly
 
 ## When to Skip

references/final-writing.md

@@ -211,16 +211,18 @@ If the bundle contains candidate figure pages or candidate image files:
 - prefer the candidate with the strongest caption/page-context agreement
 - treat identity match and visual usability as separate gates
 - never treat a matching label or caption as sufficient approval to insert an image
-- reject caption-only crops, missing table bodies, large text/title/abstract crops, and crops with very low visual body ratio
+- reject caption-only crops, missing table bodies, table crops contaminated by running prose or another Figure/Table caption, large text/title/abstract crops, and crops with very low visual body ratio
 - if visual quality is missing, ambiguous, or failed, keep the placeholder
 - still make the final decision yourself rather than trusting the candidate ranking blindly
 
 Final-note figure rules:
 - keep the original paper numbering, such as `Fig. 1`, `Fig. 3`, `Table 2`
 - do not rename them to `图 1`, `图 2` just because of note order
 - if you replace a placeholder with a real image, keep the same paper figure id in the caption
+- if you replace a placeholder with a real image, prefer the `obsidian_embed` returned by `scripts/materialize_figure_asset.py`
 - if an important figure cannot be confidently extracted, keep a placeholder with a short explanation
 - every kept placeholder must appear directly under its most relevant analytical section; do not create catch-all sections such as `剩余图表占位`, `未放置图表`, `Remaining figures`, or `Leftover figures`
+- every kept placeholder must use the standard `[!figure]` callout format; never use ordinary paragraph markers such as `[图表占位 | Fig. 1]`, `图表占位：Table 2`, or `Figure Placeholder | Fig. 3`
 - `reject_visual_quality` means the candidate image is unsafe to insert, not that the final note must keep a placeholder for that rejected candidate
 - for survey papers, summarize repetitive representative-work figures or appendix tables in prose when they do not materially help the reader as standalone callouts
 - text may be complete even when figures are partial; do not let missing images erase textual coverage

references/model-synthesis.md

@@ -37,7 +37,7 @@ The rule is simple:
    - inspect `figure_assets[].quality_signals` when available
    - match likely figures by page proximity, caption context, and candidate snippets
    - require both identity match and visual usability before insertion
-   - fail closed on caption-only crops, missing table bodies, large text/title/abstract crops, or very low visual body ratio
+   - fail closed on caption-only crops, missing table bodies, table crops contaminated by running prose or another Figure/Table caption, large text/title/abstract crops, or very low visual body ratio
    - keep the final semantic matching decision on the model side
    Build the note in placeholder-first order:
    - plan placeholders for all major figures/tables that matter to the note
@@ -51,10 +51,11 @@ The rule is simple:
      - `> 建议位置：...`
      - `> 放置原因：...`
      - `> 当前状态：...`
+   - never use ordinary paragraph markers such as `[图表占位 | Fig. 1]`, `图表占位：Table 2`, or `Figure Placeholder | Fig. 3`
    If you decide to insert a real image instead of leaving a placeholder:
    - call `scripts/materialize_figure_asset.py`
    - copy the chosen candidate image into the vault
-   - insert the returned Obsidian embed into the note
+   - insert the returned Obsidian embed into the note; Markdown image syntax is a compatibility fallback, not the preferred note format
    This figure step belongs to the same note-generation task:
    - do not stop after a text-only draft just to ask the user whether figures should be inserted
    - finish the replacement-or-placeholder decision before final save

scripts/build_synthesis_bundle.py

@@ -365,11 +365,13 @@ def bundle(metadata: dict, evidence_wrapper: dict, figures_wrapper: dict, assets
             "figure_rules": [
                 "先规划主要图表的占位标签，再决定哪些可以替换成真实图片",
                 "label/caption match is not insertion approval; it only proves identity, and visual usability is a separate hard gate.",
-                "Reject caption-only crops, missing table body crops, large text/title/abstract crops, and low visual body ratio crops.",
+                "Reject caption-only crops, missing table body crops, table crops with paragraph or other-caption contamination, large text/title/abstract crops, and low visual body ratio crops.",
                 "If visual quality is missing, ambiguous, or marked review/reject, fail closed: keep the placeholder instead of inserting the image.",
                 "Every kept placeholder must appear directly under the most relevant analytical section named by its `建议位置`; do not collect unresolved placeholders in catch-all sections such as `剩余图表占位`, `未放置图表`, `Remaining figures`, or `Leftover figures`.",
+                "Every kept placeholder must use the standard `> [!figure]` callout with `建议位置`, `放置原因`, and `当前状态`; never use plain paragraph placeholders such as `[图表占位 | Fig. 1]`, `图表占位：Table 2`, or `Figure Placeholder | Fig. 3`.",
                 "`reject_visual_quality` means the candidate image is unsafe to insert; it does not require keeping a final-note placeholder for every rejected candidate.",
                 "For survey papers, summarize repetitive representative-work figures or appendix tables in prose when they do not materially help the reader as standalone callouts.",
+                "When inserting a real image, prefer the `obsidian_embed` returned by materialize_figure_asset.py; Markdown image syntax is a compatibility fallback, not the preferred note format.",
                 "如果没有高置信度图像匹配，不要删除占位标签",
                 "图注必须保留论文原始编号，例如 Fig. 1、Table 2",
                 "如果插入的是局部子图或不完整裁剪，必须明确说明",

scripts/extract_pdf_assets.py

@@ -91,20 +91,26 @@ def _classify_visual_quality(
     paragraph_text_chars: int,
     table_body_rows: int,
     caption_text_chars: int,
+    other_caption_labels: list[str] | None = None,
 ) -> dict:
     """Classify whether a caption-matched crop is visually usable.
 
     This is intentionally conservative. A label/caption match proves identity,
     but not that the rendered crop contains the figure or table body.
     """
     normalized_kind = kind.strip().lower()
+    other_caption_labels = list(other_caption_labels or [])
     reasons: list[str] = []
 
     if normalized_kind == "table":
         if table_body_rows <= 0:
             reasons.append("table_body_missing")
         if table_body_rows <= 1 and visual_body_ratio < 0.03 and caption_text_chars >= 40:
             reasons.append("caption_only_suspected")
+        if paragraph_text_chars >= 450:
+            reasons.append("table_text_contamination_suspected")
+        if other_caption_labels:
+            reasons.append("multiple_caption_regions_suspected")
         status = "reject" if reasons else "usable"
     else:
         if paragraph_text_chars >= 450:
@@ -131,6 +137,8 @@ def _classify_visual_quality(
         "paragraph_text_chars": int(paragraph_text_chars),
         "table_body_rows": int(table_body_rows),
         "caption_text_chars": int(caption_text_chars),
+        "other_caption_count": len(other_caption_labels),
+        "other_caption_labels": other_caption_labels,
     }
 
 
@@ -434,6 +442,34 @@ def _count_paragraph_text_chars_in_bbox(
     return chars
 
 
+def _other_caption_labels_for_crop(
+    caption_anchors: list[dict],
+    current_anchor: dict,
+    bbox: tuple[float, float, float, float],
+) -> list[str]:
+    """Return other caption labels substantially covered by this crop."""
+    labels: list[str] = []
+    current_label = normalize_whitespace(str(current_anchor.get("label", "")))
+    current_bbox = tuple(current_anchor.get("bbox", ()))
+
+    for anchor in caption_anchors:
+        label = normalize_whitespace(str(anchor.get("label", "")))
+        anchor_bbox = tuple(anchor.get("bbox", ()))
+        if not label or len(anchor_bbox) != 4:
+            continue
+        if label == current_label and anchor_bbox == current_bbox:
+            continue
+
+        overlap = _intersection_area(anchor_bbox, bbox)
+        if overlap <= 0:
+            continue
+        if overlap / max(_rect_area(anchor_bbox), 1.0) < 0.5:
+            continue
+        labels.append(label)
+
+    return sorted(set(labels))
+
+
 def _quality_signals_for_crop(
     page,
     kind: str,
@@ -442,13 +478,15 @@ def _quality_signals_for_crop(
     page_rect,
     *,
     table_body_rows: int,
+    caption_anchors: list[dict] | None = None,
 ) -> dict:
     page_area = _rect_area((page_rect.x0, page_rect.y0, page_rect.x1, page_rect.y1))
     page_coverage_ratio = _rect_area(bbox) / page_area if page_area > 0 else 0.0
     visual_rect_count, visual_body_ratio = _visual_signal_for_bbox(page, bbox)
     caption_bbox = tuple(caption_anchor["bbox"])
     paragraph_text_chars = _count_paragraph_text_chars_in_bbox(page, bbox, caption_bbox)
     caption_text_chars = len(normalize_whitespace(str(caption_anchor.get("line_text", ""))))
+    other_caption_labels = _other_caption_labels_for_crop(caption_anchors or [], caption_anchor, bbox)
     return _classify_visual_quality(
         kind=kind,
         page_coverage_ratio=page_coverage_ratio,
@@ -457,6 +495,7 @@ def _quality_signals_for_crop(
         paragraph_text_chars=paragraph_text_chars,
         table_body_rows=table_body_rows,
         caption_text_chars=caption_text_chars,
+        other_caption_labels=other_caption_labels,
     )
 
 
@@ -897,6 +936,7 @@ def extract_figure_regions(
             anchor,
             page_rect,
             table_body_rows=table_body_rows,
+            caption_anchors=anchors,
         )
 
         assets.append(

scripts/lint_note.py

@@ -68,6 +68,21 @@
     "placeholders",
 }
 
+NONSTANDARD_FIGURE_PLACEHOLDER_RE = re.compile(
+    r"""(?ix)
+    ^\s*
+    (?:
+        \[\s*(?:图表|图片|图|表)\s*占位\s*\|[^\]]+\]
+        |
+        (?:图表|图片|图|表)\s*占位\s*[:：]\s*\S+
+        |
+        \[\s*(?:figure|fig|table)\s+placeholder\s*(?:\||:|\]|-|\s+(?:fig(?:ure)?|table)\.?\s*\d)
+        |
+        (?:figure|fig|table)\s+placeholder\s*(?:\||:|-|\s+(?:fig(?:ure)?|table)\.?\s*\d)
+    )
+    """
+)
+
 
 def parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(description=__doc__ or "lint note")
@@ -359,6 +374,23 @@ def figure_bucket_heading_issues(text: str) -> list[dict[str, object]]:
     return issues
 
 
+def nonstandard_figure_placeholder_issues(text: str) -> list[dict[str, object]]:
+    issues: list[dict[str, object]] = []
+    for idx, line in enumerate(text.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith(">"):
+            continue
+        if NONSTANDARD_FIGURE_PLACEHOLDER_RE.match(stripped):
+            issues.append(
+                {
+                    "line_number": idx,
+                    "line": stripped,
+                    "reason": "nonstandard_figure_placeholder_format",
+                }
+            )
+    return issues
+
+
 def figure_callout_placement_issues(text: str) -> list[dict[str, object]]:
     issues: list[dict[str, object]] = []
     lines = text.splitlines()
@@ -420,7 +452,11 @@ def figure_callout_placement_issues(text: str) -> list[dict[str, object]]:
 
 
 def figure_structure_issues(text: str) -> list[dict[str, object]]:
-    return figure_bucket_heading_issues(text) + figure_callout_placement_issues(text)
+    return (
+        figure_bucket_heading_issues(text)
+        + nonstandard_figure_placeholder_issues(text)
+        + figure_callout_placement_issues(text)
+    )
 
 
 def figure_structure_passes(text: str) -> bool:

tests/test_extract_evidence.py

@@ -141,3 +141,5 @@ def test_bundle_exposes_sanitized_figure_asset_quality_and_hard_gate_rules() ->
     assert "directly under the most relevant analytical section" in figure_rules_text
     assert "reject_visual_quality" in figure_rules_text
     assert "catch-all sections" in figure_rules_text
+    assert "[!figure]" in figure_rules_text
+    assert "[图表占位 |" in figure_rules_text

tests/test_extract_pdf_assets_quality.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from extract_pdf_assets import _classify_visual_quality
+from extract_pdf_assets import _classify_visual_quality, _other_caption_labels_for_crop
 
 
 def test_quality_classification_rejects_table_without_body_rows() -> None:
@@ -33,6 +33,63 @@ def test_quality_classification_rejects_caption_only_crop() -> None:
     assert "caption_only_suspected" in signals["quality_reason_codes"]
 
 
+def test_quality_classification_rejects_table_with_paragraph_text_contamination() -> None:
+    signals = _classify_visual_quality(
+        kind="table",
+        page_coverage_ratio=0.14,
+        visual_rect_count=4,
+        visual_body_ratio=0.18,
+        paragraph_text_chars=620,
+        table_body_rows=6,
+        caption_text_chars=80,
+    )
+
+    assert signals["visual_quality_status"] == "reject"
+    assert "table_text_contamination_suspected" in signals["quality_reason_codes"]
+
+
+def test_quality_classification_rejects_table_covering_other_caption() -> None:
+    signals = _classify_visual_quality(
+        kind="table",
+        page_coverage_ratio=0.18,
+        visual_rect_count=6,
+        visual_body_ratio=0.22,
+        paragraph_text_chars=40,
+        table_body_rows=8,
+        caption_text_chars=90,
+        other_caption_labels=["Table 8"],
+    )
+
+    assert signals["visual_quality_status"] == "reject"
+    assert signals["other_caption_labels"] == ["Table 8"]
+    assert "multiple_caption_regions_suspected" in signals["quality_reason_codes"]
+
+
+def test_other_caption_labels_for_crop_detects_substantial_overlap() -> None:
+    current = {"label": "Table 7", "bbox": (10.0, 10.0, 80.0, 24.0)}
+    other = {"label": "Table 8", "bbox": (12.0, 120.0, 82.0, 136.0)}
+
+    labels = _other_caption_labels_for_crop([current, other], current, (0.0, 0.0, 100.0, 140.0))
+
+    assert labels == ["Table 8"]
+
+
+def test_quality_classification_accepts_clean_table_crop() -> None:
+    signals = _classify_visual_quality(
+        kind="table",
+        page_coverage_ratio=0.16,
+        visual_rect_count=5,
+        visual_body_ratio=0.16,
+        paragraph_text_chars=70,
+        table_body_rows=7,
+        caption_text_chars=70,
+        other_caption_labels=[],
+    )
+
+    assert signals["visual_quality_status"] == "usable"
+    assert signals["quality_reason_codes"] == []
+
+
 def test_quality_classification_rejects_large_text_page_crop() -> None:
     signals = _classify_visual_quality(
         kind="figure",