fix: is_blank_frame双条件检测 + CSV列错位修复 + 自检逻辑 + 单元测试

doco/tests/test_video_split.py

@@ -17,7 +17,7 @@ from doco.src.video_split import (
     hamming_distance,
     format_timestamp,
     build_b_manuscript,
-    compute_phash,
+    is_blank_frame,
 )
 
 
@@ -139,3 +139,67 @@ class TestKeyframesJson:
         assert loaded["phash_threshold"] == 8
         assert len(loaded["keyframes"]) == 1
         assert loaded["keyframes"][0]["frame_index"] == 0
+
+
+class TestIsBlankFrame:
+    """is_blank_frame 双条件检测单元测试"""
+
+    def test_pure_black_frame(self, tmp_path):
+        """全 0 纯黑图:max_brightness=0,white_ratio=0,is_blank=True"""
+        from PIL import Image
+        img_path = tmp_path / "black.png"
+        img = Image.new("L", (100, 100), 0)  # 全黑
+        img.save(img_path)
+
+        is_blank, white_ratio, max_brightness = is_blank_frame(img_path)
+        assert is_blank is True
+        assert max_brightness == 0
+        assert white_ratio == 0.0
+
+    def test_subtitle_frame(self, tmp_path):
+        """有少量白像素(亮度255,占~1%)的图:is_blank=False"""
+        from PIL import Image
+        import numpy as np
+        img_path = tmp_path / "subtitle.png"
+        arr = np.zeros((100, 100), dtype=np.uint8)
+        # 1% 白像素(亮度255),其余黑(亮度0)
+        arr[:100, :10] = 255
+        img = Image.fromarray(arr, mode="L")
+        img.save(img_path)
+
+        is_blank, white_ratio, max_brightness = is_blank_frame(img_path)
+        assert is_blank is False
+        assert max_brightness == 255
+        assert 0.005 <= white_ratio <= 0.02  # ~1%
+
+    def test_max_brightness_ok_but_ratio_too_low(self, tmp_path):
+        """max_brightness>=240 但 white_ratio<0.005 → is_blank=True"""
+        from PIL import Image
+        import numpy as np
+        img_path = tmp_path / "few_pixels.png"
+        arr = np.zeros((100, 100), dtype=np.uint8)
+        # 只有 0.1% 白像素(不够 0.5%),但 max_brightness=255
+        arr[:10, :1] = 255
+        img = Image.fromarray(arr, mode="L")
+        img.save(img_path)
+
+        is_blank, white_ratio, max_brightness = is_blank_frame(img_path)
+        assert is_blank is True
+        assert max_brightness == 255
+        assert white_ratio < 0.005
+
+    def test_ratio_ok_but_max_brightness_too_low(self, tmp_path):
+        """white_ratio>=0.005 但 max_brightness<240 → is_blank=True"""
+        from PIL import Image
+        import numpy as np
+        img_path = tmp_path / "dim_pixels.png"
+        arr = np.zeros((100, 100), dtype=np.uint8)
+        # 1% 像素亮度=220(不够240阈值),其余黑
+        arr[:100, :10] = 220
+        img = Image.fromarray(arr, mode="L")
+        img.save(img_path)
+
+        is_blank, white_ratio, max_brightness = is_blank_frame(img_path)
+        assert is_blank is True
+        assert max_brightness == 220
+        assert white_ratio >= 0.005