Prevent catch-all figure placeholder sections

917Dhj · 917Dhj · commit dd85992fe657 · 2026-05-17T00:01:15.000+08:00
diff --git a/SKILL.md b/SKILL.md
@@ -132,6 +132,7 @@ Local-library-first rule (applies only when the Zotero check above succeeds):
 - The `创新点` section should not be empty praise. It should enumerate the paper's actual innovations and briefly explain why each one matters.
 - 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`.
 - Real images may replace some placeholders, but only if they clearly match the corresponding paper figure/table.
 - 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.
diff --git a/references/figure-placement.md b/references/figure-placement.md
@@ -45,6 +45,20 @@ Do not let scripts make the final semantic choice; scripts should only prepare c
 - Do not produce a text-only note first and then ask the user in a follow-up whether figures should be inserted.
 - If no figure can be confidently replaced, finish the note with placeholders and explain that outcome in the final response.
 
+## Integrated Placement Rule
+
+Every kept placeholder must be placed directly under the most relevant substantive section named by its `建议位置`.
+Do not collect unresolved placeholders into a catch-all section such as `剩余图表占位`, `未放置图表`, `Remaining figures`, or `Leftover figures`.
+
+`reject_visual_quality` means the candidate image must not be inserted.
+It does not by itself require a final-note placeholder.
+The final placeholder set should come from semantic importance to the note, not from the number of failed extraction candidates.
+
+For survey papers with many representative project figures, appendix tables, or repetitive supplemental visuals:
+- keep a callout only when the visual materially helps the reader understand the argument
+- otherwise summarize the pattern in prose or point the reader back to the appendix/source paper
+- do not stack low-value callouts just to demonstrate that the pipeline saw them
+
 ## Visual Quality Gate
 
 Figure/table insertion has two separate gates:
diff --git a/references/final-writing.md b/references/final-writing.md
@@ -220,6 +220,9 @@ Final-note figure rules:
 - 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 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`
+- `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
 - complete the figure decision inside the same task as the note generation
 - do not stop after the text draft and ask the user whether to continue with figures unless they explicitly asked for a staged workflow
diff --git a/references/model-synthesis.md b/references/model-synthesis.md
@@ -43,6 +43,9 @@ The rule is simple:
    - plan placeholders for all major figures/tables that matter to the note
    - replace a placeholder with a real image only when the candidate is good enough
    - keep the original paper figure/table id in either case
+   - place every kept placeholder directly under its most relevant analytical section; never create catch-all sections such as `剩余图表占位`, `未放置图表`, `Remaining figures`, or `Leftover figures`
+   - treat `reject_visual_quality` as "do not insert this image", not as an obligation to keep a final-note placeholder for every rejected candidate
+   - for surveys, use prose rather than stacked callouts for repetitive representative-work figures or appendix tables that do not materially help the reader
    - when keeping a placeholder, use the stable four-line callout format:
      - `> [!figure] Fig. 3 ...`
      - `> 建议位置：...`
diff --git a/scripts/build_synthesis_bundle.py b/scripts/build_synthesis_bundle.py
@@ -367,6 +367,9 @@ def bundle(metadata: dict, evidence_wrapper: dict, figures_wrapper: dict, assets
                 "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.",
                 "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`.",
+                "`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.",
                 "如果没有高置信度图像匹配，不要删除占位标签",
                 "图注必须保留论文原始编号，例如 Fig. 1、Table 2",
                 "如果插入的是局部子图或不完整裁剪，必须明确说明",
diff --git a/scripts/lint_note.py b/scripts/lint_note.py
@@ -23,6 +23,51 @@
     "引用",
 ]
 
+FIGURE_TARGET_SECTIONS = {
+    "研究问题",
+    "数据与任务定义",
+    "方法主线",
+    "关键结果",
+    "深度分析",
+    "局限",
+    "我的笔记",
+}
+
+FIGURE_BUCKET_RESIDUE_TOKENS = {
+    "剩余",
+    "残余",
+    "未放置",
+    "未处理",
+    "待补",
+}
+
+FIGURE_BUCKET_VISUAL_TOKENS = {
+    "图",
+    "表",
+    "图片",
+    "图表",
+    "占位",
+}
+
+ENGLISH_FIGURE_BUCKET_RESIDUE_TOKENS = {
+    "remaining",
+    "leftover",
+    "unplaced",
+    "unresolved",
+    "backlog",
+}
+
+ENGLISH_FIGURE_BUCKET_VISUAL_TOKENS = {
+    "figure",
+    "figures",
+    "fig",
+    "figs",
+    "table",
+    "tables",
+    "placeholder",
+    "placeholders",
+}
+
 
 def parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(description=__doc__ or "lint note")
@@ -285,6 +330,103 @@ def inspect_figure_callouts(text: str) -> list[str]:
     return warnings
 
 
+def is_figure_bucket_heading(title: str) -> bool:
+    normalized = title.strip().lower()
+    has_chinese_residue = any(token in normalized for token in FIGURE_BUCKET_RESIDUE_TOKENS)
+    has_chinese_visual = any(token in normalized for token in FIGURE_BUCKET_VISUAL_TOKENS)
+    if has_chinese_residue and has_chinese_visual:
+        return True
+    has_english_residue = any(token in normalized for token in ENGLISH_FIGURE_BUCKET_RESIDUE_TOKENS)
+    has_english_visual = any(token in normalized for token in ENGLISH_FIGURE_BUCKET_VISUAL_TOKENS)
+    return has_english_residue and has_english_visual
+
+
+def figure_bucket_heading_issues(text: str) -> list[dict[str, object]]:
+    issues: list[dict[str, object]] = []
+    for idx, line in enumerate(text.splitlines(), start=1):
+        match = re.match(r"^(#{2,3})\s+(.+)$", line.strip())
+        if not match:
+            continue
+        heading = match.group(2).strip()
+        if is_figure_bucket_heading(heading):
+            issues.append(
+                {
+                    "line_number": idx,
+                    "heading": heading,
+                    "reason": "figure_placeholder_bucket_heading",
+                }
+            )
+    return issues
+
+
+def figure_callout_placement_issues(text: str) -> list[dict[str, object]]:
+    issues: list[dict[str, object]] = []
+    lines = text.splitlines()
+    for idx, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith("[FIGURE_PLACEHOLDER]"):
+            issues.append(
+                {
+                    "line_number": idx + 1,
+                    "line": stripped,
+                    "reason": "legacy_figure_placeholder_block_used",
+                }
+            )
+            continue
+        if not stripped.startswith("> [!figure]"):
+            continue
+
+        current_section = section_name_for_line(lines, idx)
+        current_subsection = subsection_name_for_line(lines, idx)
+        location = ""
+        j = idx + 1
+        while j < len(lines):
+            nxt = lines[j].strip()
+            if not nxt.startswith(">"):
+                break
+            if nxt.startswith("> 建议位置："):
+                location = nxt.removeprefix("> 建议位置：").strip()
+                break
+            j += 1
+
+        if not location:
+            issues.append(
+                {
+                    "line_number": idx + 1,
+                    "callout": stripped,
+                    "current_section": current_section,
+                    "current_subsection": current_subsection,
+                    "reason": "figure_callout_missing_location",
+                }
+            )
+            continue
+
+        if current_subsection and current_subsection in location:
+            continue
+        target_sections = [section for section in FIGURE_TARGET_SECTIONS if section in location]
+        if target_sections and current_section not in target_sections:
+            issues.append(
+                {
+                    "line_number": idx + 1,
+                    "callout": stripped,
+                    "current_section": current_section,
+                    "current_subsection": current_subsection,
+                    "declared_location": location,
+                    "target_sections": target_sections,
+                    "reason": "figure_callout_placement_mismatch",
+                }
+            )
+    return issues
+
+
+def figure_structure_issues(text: str) -> list[dict[str, object]]:
+    return figure_bucket_heading_issues(text) + figure_callout_placement_issues(text)
+
+
+def figure_structure_passes(text: str) -> bool:
+    return not figure_structure_issues(text)
+
+
 def is_prose_line(line: str) -> bool:
     stripped = line.strip()
     if not stripped:
@@ -653,7 +795,12 @@ def main() -> None:
     linebreak_issues = suspicious_mid_sentence_linebreaks(body_text)
     code_math_issues = suspicious_code_formatted_math(text)
     math_issues = math_render_issues(text)
+    figure_issues = figure_structure_issues(text)
     warnings.extend(inspect_figure_callouts(text))
+    for issue in figure_issues:
+        reason = str(issue.get("reason", ""))
+        if reason and reason not in warnings:
+            warnings.append(reason)
     warnings.extend(front_matter_order_warnings(text))
     warnings.extend(mechanism_flow_warnings(text))
     if not body_text.lstrip().startswith("# "):
@@ -689,9 +836,11 @@ def main() -> None:
         "linebreak_issues": linebreak_issues,
         "code_math_issues": code_math_issues,
         "math_render_issues": math_issues,
+        "figure_structure_issues": figure_issues,
         "passes_basic_structure": not missing_sections and not {"title_heading_missing", "no_level2_sections", "front_matter_order_invalid"} & set(warnings),
         "passes_style_gate": not mixed_issues and not linebreak_issues and not code_math_issues,
         "passes_math_gate": not math_issues,
+        "passes_figure_gate": not figure_issues,
     }
     emit(payload, args.output)
 
diff --git a/scripts/write_obsidian_note.py b/scripts/write_obsidian_note.py
@@ -52,6 +52,8 @@ def main() -> None:
             raise SystemExit("write_obsidian_note.py refused to write note because style gate failed.")
         if not lint.get("passes_math_gate", False):
             raise SystemExit("write_obsidian_note.py refused to write note because math gate failed.")
+        if "passes_figure_gate" in lint and not lint.get("passes_figure_gate", False):
+            raise SystemExit("write_obsidian_note.py refused to write note because figure gate failed.")
 
     if args.content_file:
         note_text = Path(args.content_file).expanduser().resolve().read_text(encoding="utf-8")
diff --git a/tests/test_cli_fallback.py b/tests/test_cli_fallback.py
@@ -132,3 +132,79 @@ def test_write_note_refuses_when_math_gate_fails(tmp_path: Path) -> None:
     )
     assert result.returncode != 0
     assert "math gate failed" in result.stderr
+
+
+def test_write_note_accepts_legacy_lint_json_without_figure_gate(tmp_path: Path) -> None:
+    lint_path = tmp_path / "lint.json"
+    lint_path.write_text(
+        json.dumps(
+            {
+                "passes_basic_structure": True,
+                "passes_style_gate": True,
+                "passes_math_gate": True,
+            }
+        ),
+        encoding="utf-8",
+    )
+    env = os.environ.copy()
+    env.pop("DEEPPAPERNOTE_OBSIDIAN_VAULT", None)
+    env.pop("READ_ARXIV_OBSIDIAN_VAULT", None)
+    env["DEEPPAPERNOTE_WORKSPACE_OUTPUT_DIR"] = "DeepPaperNote_output"
+    env["DEEPPAPERNOTE_DISABLE_SHELL_CONFIG"] = "1"
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            str(WRITE_SCRIPT),
+            "--title",
+            "Legacy Lint Test",
+            "--content",
+            "# Legacy Lint Test\n\nBody.\n",
+            "--lint-json",
+            str(lint_path),
+        ],
+        cwd=tmp_path,
+        env=env,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    payload = json.loads(result.stdout)
+    assert Path(payload["note_path"]).exists()
+
+
+def test_write_note_refuses_when_figure_gate_fails(tmp_path: Path) -> None:
+    lint_path = tmp_path / "lint.json"
+    lint_path.write_text(
+        json.dumps(
+            {
+                "passes_basic_structure": True,
+                "passes_style_gate": True,
+                "passes_math_gate": True,
+                "passes_figure_gate": False,
+            }
+        ),
+        encoding="utf-8",
+    )
+    env = os.environ.copy()
+    env["DEEPPAPERNOTE_DISABLE_SHELL_CONFIG"] = "1"
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            str(WRITE_SCRIPT),
+            "--title",
+            "Figure Gate Test",
+            "--content",
+            "# Figure Gate Test\n\nBody.\n",
+            "--lint-json",
+            str(lint_path),
+        ],
+        cwd=tmp_path,
+        env=env,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode != 0
+    assert "figure gate failed" in result.stderr
diff --git a/tests/test_extract_evidence.py b/tests/test_extract_evidence.py
@@ -138,3 +138,6 @@ def test_bundle_exposes_sanitized_figure_asset_quality_and_hard_gate_rules() ->
     assert "caption-only" in figure_rules_text
     assert "missing table body" in figure_rules_text
     assert "low visual body ratio" in figure_rules_text
+    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
diff --git a/tests/test_lint_note.py b/tests/test_lint_note.py
