From 37b3bf8db2b272b58d689bcb0891a0425ca5d3e8 Mon Sep 17 00:00:00 2001
From: CI Bot <ci-bot@xiaoxiajianji.com>
Date: Sat, 25 Jul 2026 10:21:01 +0800
Subject: [PATCH 1/3] =?UTF-8?q?test:=20=E7=AC=AC73=E6=B3=A2=20url=5Fsecuri?=
 =?UTF-8?q?ty=20+=20pagination=20+=20text=5Fsplitter=20=E5=8D=95=E6=B5=8B?=
 =?UTF-8?q?=20(+144)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- test_url_security: URL安全校验（SSRF防护/魔数校验/可信域名/直接IP拦截） ~85个
- test_pagination: 分页器（参数校验/偏移计算/元数据/内存分页） ~35个
- test_text_splitter: 文本分段器（句子边界/强制切段/短段合并） ~24个

全部纯逻辑，无外部依赖
---
 tests/unit/test_pagination.py    |  347 ++++++----
 tests/unit/test_text_splitter.py |  286 +++++----
 tests/unit/test_url_security.py  | 1027 ++++++++++++++----------------
 3 files changed, 871 insertions(+), 789 deletions(-)

diff --git a/tests/unit/test_pagination.py b/tests/unit/test_pagination.py
index 9d9dcc7c1..a39c49cf1 100755
--- a/tests/unit/test_pagination.py
+++ b/tests/unit/test_pagination.py
@@ -1,11 +1,16 @@
-"""通用分页器单元测试."""
+"""分页器纯逻辑测试 — PaginationParams/PaginationMeta/paginate.
+
+覆盖参数校验、偏移计算、元数据计算、内存分页等全部纯逻辑。
+"""
 
 from __future__ import annotations
 
+from math import ceil
+
 import pytest
 from pydantic import ValidationError
 
-from packages.application.common.pagination import (
+from application.common.pagination import (
     PaginatedResponse,
     PaginationMeta,
     PaginationParams,
@@ -13,232 +18,302 @@ from packages.application.common.pagination import (
 )
 
 
-class TestPaginationParams:
-    """PaginationParams 测试"""
+class TestPaginationParamsDefaults:
+    """PaginationParams 默认值与属性."""
 
-    def test_default_values(self):
-        """默认值正确"""
+    def test_default_page_is_1(self):
+        """默认页码为1."""
         params = PaginationParams()
         assert params.page == 1
+
+    def test_default_page_size_is_20(self):
+        """默认每页20条."""
+        params = PaginationParams()
         assert params.page_size == 20
 
-    def test_offset_first_page(self):
-        """第一页 offset 为 0"""
+    def test_offset_first_page_is_0(self):
+        """第一页偏移量为0."""
         params = PaginationParams(page=1, page_size=20)
         assert params.offset == 0
 
     def test_offset_second_page(self):
-        """第二页 offset 计算正确"""
+        """第二页偏移量=page_size."""
         params = PaginationParams(page=2, page_size=20)
         assert params.offset == 20
 
-    def test_offset_custom_page_size(self):
-        """自定义 page_size 的 offset"""
+    def test_offset_page_3_size_10(self):
+        """第3页每页10条，偏移20."""
         params = PaginationParams(page=3, page_size=10)
         assert params.offset == 20
 
     def test_limit_equals_page_size(self):
-        """limit 等于 page_size"""
+        """limit等于page_size."""
         params = PaginationParams(page_size=50)
         assert params.limit == 50
 
-    def test_page_must_be_at_least_1(self):
-        """page 不能小于 1"""
+
+class TestPaginationParamsValidation:
+    """PaginationParams 参数校验."""
+
+    def test_page_zero_rejected(self):
+        """页码0被拒绝."""
         with pytest.raises(ValidationError):
             PaginationParams(page=0)
 
-    def test_page_negative_raises(self):
-        """page 不能为负数"""
+    def test_page_negative_rejected(self):
+        """负页码被拒绝."""
         with pytest.raises(ValidationError):
             PaginationParams(page=-1)
 
-    def test_page_size_must_be_at_least_1(self):
-        """page_size 不能小于 1"""
+    def test_page_size_zero_rejected(self):
+        """每页0条被拒绝."""
         with pytest.raises(ValidationError):
             PaginationParams(page_size=0)
 
-    def test_page_size_max_100(self):
-        """page_size 最大 100"""
+    def test_page_size_negative_rejected(self):
+        """负每页条数被拒绝."""
+        with pytest.raises(ValidationError):
+            PaginationParams(page_size=-5)
+
+    def test_page_size_over_100_rejected(self):
+        """每页超过100条被拒绝."""
         with pytest.raises(ValidationError):
             PaginationParams(page_size=101)
 
-    def test_page_size_100_is_valid(self):
-        """page_size=100 是合法的"""
+    def test_page_size_100_allowed(self):
+        """每页100条允许."""
         params = PaginationParams(page_size=100)
         assert params.page_size == 100
 
+    def test_page_size_1_allowed(self):
+        """每页1条允许."""
+        params = PaginationParams(page_size=1)
+        assert params.page_size == 1
 
-class TestPaginationMeta:
-    """PaginationMeta 测试"""
+    def test_page_1_allowed(self):
+        """页码1允许."""
+        params = PaginationParams(page=1)
+        assert params.page == 1
 
-    def test_from_params_first_page(self):
-        """第一页元数据"""
+    def test_large_page_allowed(self):
+        """大页码允许（不设上限）."""
+        params = PaginationParams(page=9999)
+        assert params.page == 9999
+
+
+class TestPaginationMetaFromParams:
+    """PaginationMeta.from_params 元数据计算."""
+
+    def test_first_page_has_prev_false(self):
+        """第一页没有上一页."""
         params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=25)
-
-        assert meta.page == 1
-        assert meta.page_size == 10
-        assert meta.total == 25
-        assert meta.total_pages == 3
-        assert meta.has_next is True
+        meta = PaginationMeta.from_params(params, total=100)
         assert meta.has_prev is False
 
-    def test_from_params_last_page(self):
-        """最后一页元数据"""
-        params = PaginationParams(page=3, page_size=10)
-        meta = PaginationMeta.from_params(params, total=25)
-
-        assert meta.page == 3
-        assert meta.total_pages == 3
-        assert meta.has_next is False
-        assert meta.has_prev is True
-
-    def test_from_params_middle_page(self):
-        """中间页元数据"""
-        params = PaginationParams(page=2, page_size=10)
-        meta = PaginationMeta.from_params(params, total=50)
-
-        assert meta.page == 2
-        assert meta.total_pages == 5
+    def test_first_page_has_next_true(self):
+        """第一页（数据多时有下一页."""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=100)
         assert meta.has_next is True
+
+    def test_last_page_has_next_false(self):
+        """最后一页没有下一页."""
+        params = PaginationParams(page=10, page_size=10)
+        meta = PaginationMeta.from_params(params, total=100)
+        assert meta.has_next is False
+
+    def test_last_page_has_prev_true(self):
+        """最后一页有上一页."""
+        params = PaginationParams(page=10, page_size=10)
+        meta = PaginationMeta.from_params(params, total=100)
         assert meta.has_prev is True
 
-    def test_from_params_zero_total(self):
-        """总数为 0 时"""
-        params = PaginationParams(page=1, page_size=20)
+    def test_middle_page_has_both(self):
+        """中间页上下都有."""
+        params = PaginationParams(page=5, page_size=10)
+        meta = PaginationMeta.from_params(params, total=100)
+        assert meta.has_prev is True
+        assert meta.has_next is True
+
+    def test_total_pages_exact_division(self):
+        """整除时总页数正确."""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=100)
+        assert meta.total_pages == 10
+
+    def test_total_pages_with_remainder(self):
+        """有余数时向上取整."""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=105)
+        assert meta.total_pages == 11
+
+    def test_total_pages_single_item(self):
+        """1条数据总页数=1."""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=1)
+        assert meta.total_pages == 1
+
+    def test_total_zero_gives_zero_pages(self):
+        """0条数据总页数=0."""
+        params = PaginationParams(page=1, page_size=10)
         meta = PaginationMeta.from_params(params, total=0)
-
-        assert meta.total == 0
         assert meta.total_pages == 0
-        assert meta.has_next is False
+
+    def test_total_zero_has_prev_false(self):
+        """0条数据has_prev=False."""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=0)
         assert meta.has_prev is False
 
-    def test_from_params_exact_multiple(self):
-        """总数刚好是 page_size 的整数倍"""
+    def test_total_zero_has_next_false(self):
+        """0条数据has_next=False."""
         params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=30)
+        meta = PaginationMeta.from_params(params, total=0)
+        assert meta.has_next is False
 
-        assert meta.total_pages == 3
-
-    def test_from_params_single_page(self):
-        """单页即可放下所有数据"""
-        params = PaginationParams(page=1, page_size=100)
+    def test_page_exactly_total_pages_no_next(self):
+        """当前页等于总页数时没有下一页."""
+        params = PaginationParams(page=5, page_size=10)
         meta = PaginationMeta.from_params(params, total=50)
+        assert meta.has_next is False
+        assert meta.total_pages == 5
 
+    def test_page_beyond_total_pages(self):
+        """页码超过总页数时has_next=False."""
+        params = PaginationParams(page=20, page_size=10)
+        meta = PaginationMeta.from_params(params, total=50)
+        assert meta.has_next is False
+        assert meta.has_prev is True
+
+    def test_preserves_page_and_page_size(self):
+        """保留输入的page和page_size."""
+        params = PaginationParams(page=3, page_size=25)
+        meta = PaginationMeta.from_params(params, total=200)
+        assert meta.page == 3
+        assert meta.page_size == 25
+        assert meta.total == 200
+
+    def test_page_size_1_total_1(self):
+        """每页1条，1条数据."""
+        params = PaginationParams(page=1, page_size=1)
+        meta = PaginationMeta.from_params(params, total=1)
         assert meta.total_pages == 1
         assert meta.has_next is False
         assert meta.has_prev is False
 
 
-class TestPaginatedResponse:
-    """PaginatedResponse 测试"""
+class TestPaginatedResponseCreate:
+    """PaginatedResponse.create 创建分页响应."""
 
-    def test_create_success(self):
-        """创建分页响应"""
+    def test_creates_with_data_and_meta(self):
+        """创建包含data和pagination."""
         params = PaginationParams(page=1, page_size=10)
-        data = [1, 2, 3]
+        data = [{"id": i} for i in range(10)]
+        resp = PaginatedResponse.create(data, params, total=25)
+        assert resp.data == data
+        assert resp.pagination.page == 1
+        assert resp.pagination.total == 25
+        assert resp.pagination.total_pages == 3
 
-        response = PaginatedResponse.create(data, params, total=25)
-
-        assert response.data == [1, 2, 3]
-        assert response.pagination.page == 1
-        assert response.pagination.total == 25
-        assert response.pagination.total_pages == 3
-
-    def test_create_empty_data(self):
-        """空数据分页响应"""
-        params = PaginationParams(page=1, page_size=20)
-        response = PaginatedResponse.create([], params, total=0)
-
-        assert response.data == []
-        assert response.pagination.total == 0
-        assert response.pagination.total_pages == 0
+    def test_empty_data(self):
+        """空数据响应."""
+        params = PaginationParams(page=1, page_size=10)
+        resp = PaginatedResponse.create([], params, total=0)
+        assert resp.data == []
+        assert resp.pagination.total == 0
+        assert resp.pagination.total_pages == 0
 
 
-class TestPaginateFunction:
-    """paginate 函数测试（内存分页）"""
+class TestPaginateInMemory:
+    """paginate 内存分页函数."""
 
     def test_first_page(self):
-        """第一页分页"""
-        items = list(range(30))
+        """第一页返回前N条."""
+        items = list(range(50))
         params = PaginationParams(page=1, page_size=10)
-
         result = paginate(items, params)
-
         assert result.data == list(range(10))
-        assert result.pagination.total == 30
-        assert result.pagination.total_pages == 3
+        assert result.pagination.total == 50
+        assert result.pagination.total_pages == 5
         assert result.pagination.has_next is True
         assert result.pagination.has_prev is False
 
-    def test_second_page(self):
-        """第二页分页"""
-        items = list(range(30))
-        params = PaginationParams(page=2, page_size=10)
-
+    def test_middle_page(self):
+        """中间页."""
+        items = list(range(50))
+        params = PaginationParams(page=3, page_size=10)
         result = paginate(items, params)
-
-        assert result.data == list(range(10, 20))
-        assert result.pagination.page == 2
+        assert result.data == list(range(20, 30))
+        assert result.pagination.has_prev is True
+        assert result.pagination.has_next is True
 
     def test_last_page(self):
-        """最后一页分页"""
-        items = list(range(25))
-        params = PaginationParams(page=3, page_size=10)
-
+        """最后一页."""
+        items = list(range(50))
+        params = PaginationParams(page=5, page_size=10)
         result = paginate(items, params)
-
-        assert result.data == list(range(20, 25))
-        assert len(result.data) == 5
+        assert result.data == list(range(40, 50))
         assert result.pagination.has_next is False
+        assert result.pagination.has_prev is True
+
+    def test_last_page_not_full(self):
+        """最后一页不足page_size."""
+        items = list(range(45))
+        params = PaginationParams(page=5, page_size=10)
+        result = paginate(items, params)
+        assert result.data == list(range(40, 45))
+        assert len(result.data) == 5
+        assert result.pagination.total == 45
+        assert result.pagination.total_pages == 5
 
     def test_empty_list(self):
-        """空列表分页"""
-        params = PaginationParams(page=1, page_size=20)
-        result = paginate([], params)
-
+        """空列表分页."""
+        items = []
+        params = PaginationParams(page=1, page_size=10)
+        result = paginate(items, params)
         assert result.data == []
         assert result.pagination.total == 0
         assert result.pagination.total_pages == 0
 
     def test_page_beyond_total(self):
-        """页码超出总数"""
+        """页码超过总页数返回空数据."""
         items = list(range(5))
         params = PaginationParams(page=10, page_size=10)
-
         result = paginate(items, params)
-
         assert result.data == []
         assert result.pagination.total == 5
         assert result.pagination.total_pages == 1
-
-    def test_custom_page_size(self):
-        """自定义每页数量"""
-        items = list(range(100))
-        params = PaginationParams(page=1, page_size=50)
-
-        result = paginate(items, params)
-
-        assert len(result.data) == 50
-        assert result.pagination.total_pages == 2
+        assert result.pagination.has_next is False
 
     def test_single_item(self):
-        """单条数据"""
-        items = ["only_one"]
+        """单条数据分页."""
+        items = ["only"]
         params = PaginationParams(page=1, page_size=10)
-
         result = paginate(items, params)
-
-        assert result.data == ["only_one"]
+        assert result.data == ["only"]
         assert result.pagination.total == 1
         assert result.pagination.total_pages == 1
 
-    def test_generic_type_preserved(self):
-        """泛型类型数据正确"""
-        items = [{"id": 1, "name": "a"}, {"id": 2, "name": "b"}]
-        params = PaginationParams(page=1, page_size=10)
-
+    def test_page_size_larger_than_total(self):
+        """每页条数大于总数，第一页包含全部."""
+        items = list(range(5))
+        params = PaginationParams(page=1, page_size=100)
         result = paginate(items, params)
+        assert result.data == items
+        assert result.pagination.total_pages == 1
 
-        assert len(result.data) == 2
-        assert result.data[0]["id"] == 1
+    def test_page_size_1(self):
+        """每页1条."""
+        items = ["a", "b", "c"]
+        params = PaginationParams(page=2, page_size=1)
+        result = paginate(items, params)
+        assert result.data == ["b"]
+        assert result.pagination.total_pages == 3
+
+    def test_preserves_original_list(self):
+        """不修改原始列表."""
+        items = [1, 2, 3, 4, 5]
+        original = items.copy()
+        params = PaginationParams(page=1, page_size=2)
+        paginate(items, params)
+        assert items == original
diff --git a/tests/unit/test_text_splitter.py b/tests/unit/test_text_splitter.py
index d52bec9a0..13377df2e 100755
--- a/tests/unit/test_text_splitter.py
+++ b/tests/unit/test_text_splitter.py
@@ -1,147 +1,219 @@
-"""文本分段工具单元测试."""
+"""文本分段器纯逻辑测试 — split_text.
+
+覆盖空文本、短文本、句子边界分段、超长句强制切段、过短段合并等场景。
+"""
 
 from __future__ import annotations
 
 import pytest
 
-from packages.application.tts_job.text_splitter import split_text
+from application.tts_job.text_splitter import split_text
 
 
-class TestSplitText:
-    """split_text 函数测试"""
+class TestSplitTextEmptyOrShort:
+    """空文本与短文本."""
 
     def test_empty_string_returns_empty_list(self):
-        """空字符串返回空列表"""
+        """空字符串返回空列表."""
         assert split_text("") == []
 
     def test_whitespace_only_returns_empty_list(self):
-        """纯空白字符返回空列表"""
-        assert split_text("   \n  \t  ") == []
+        """纯空白字符串返回空列表."""
+        assert split_text("   \n\t  ") == []
 
-    def test_short_text_returns_single_segment(self):
-        """短文本直接返回单段"""
-        text = "这是一段短文本。"
+    def test_none_not_supported(self):
+        """None不支持（strip会报错）."""
+        with pytest.raises(AttributeError):
+            split_text(None)
+
+    def test_short_text_single_segment(self):
+        """短文本不分割，单段返回."""
+        text = "你好世界。"
         result = split_text(text, max_chars=500)
         assert result == [text]
 
-    def test_text_length_equals_max_chars(self):
-        """文本长度恰好等于 max_chars 时返回单段"""
+    def test_exactly_max_chars_single_segment(self):
+        """刚好等于max_chars时不分段."""
         text = "a" * 100
         result = split_text(text, max_chars=100)
         assert len(result) == 1
         assert len(result[0]) == 100
 
-    def test_splits_on_sentence_boundary(self):
-        """在句子边界处分段"""
-        # 构造长文本，确保超过 max_chars
-        sentences = ["今天天气真好。我们一起去公园散步吧。", "公园里有很多花。还有很多小朋友在玩耍。"] * 10
-        text = "".join(sentences)
+    def test_under_max_chars_single_segment(self):
+        """少于max_chars时不分段."""
+        text = "a" * 50
+        result = split_text(text, max_chars=100)
+        assert len(result) == 1
+        assert len(result[0]) == 50
 
-        result = split_text(text, max_chars=200)
 
+class TestSplitTextSentenceBoundary:
+    """句子边界分段."""
+
+    def test_split_by_period(self):
+        """按句号分段."""
+        text = "第一句内容。" + "第二句内容。" * 50
+        result = split_text(text, max_chars=100)
+        assert len(result) > 1
+        # 每段都不超过max_chars
+        for seg in result:
+            assert len(seg) <= 100
+        # 合并后等于原文（去空格后近似）
+        assert "".join(result) == text.replace(" ", "")
+
+    def test_split_by_question_mark(self):
+        """按问号分段."""
+        text = "你好吗？" + "我很好。" * 50
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+        for seg in result:
+            assert len(seg) <= 80
+
+    def test_split_by_exclamation_mark(self):
+        """按感叹号分段."""
+        text = "太棒了！" + "真的好。" * 50
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+
+    def test_split_by_newline(self):
+        """按换行符分段."""
+        lines = ["这是第一行很长的内容" * 5 for _ in range(10)]
+        text = "\n".join(lines)
+        result = split_text(text, max_chars=100)
+        assert len(result) > 1
+        for seg in result:
+            assert len(seg) <= 100
+
+    def test_split_by_semicolon_fullwidth(self):
+        """按全角分号分段."""
+        text = "第一项；" + "第二项内容。" * 40
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+
+    def test_split_by_english_period(self):
+        """按英文句号也分段（_SENTENCE_ENDS包含.）."""
+        text = "Hello. " + "World. " * 50
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+
+    def test_split_by_english_question(self):
+        """按英文问号分段."""
+        text = "Really? " + "Yes. " * 50
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+
+    def test_split_by_english_exclamation(self):
+        """按英文感叹号分段."""
+        text = "Wow! " + "Great. " * 50
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+
+    def test_short_sentences_not_split(self):
+        """短句（<50字）即使有句号也不立刻切，等累积到一定长度."""
+        # 每句5字，即使有句号也不会在50字前切
+        text = "你好。" * 5  # 15字符
+        result = split_text(text, max_chars=100)
+        # 因为每段至少50字才在句子边界切，所以15字的文本应该是1段
+        assert len(result) == 1
+
+
+class TestSplitTextLongSentenceForceSplit:
+    """超长单句强制切段."""
+
+    def test_single_very_long_sentence_forced_split(self):
+        """单句超长时强制切段."""
+        text = "啊" * 200  # 没有标点，200字
+        result = split_text(text, max_chars=100)
         assert len(result) >= 2
-        # 每段都不超过 max_chars
-        for seg in result:
-            assert len(seg) <= 200
-
-    def test_all_segments_within_max_chars(self):
-        """所有分段都不超过 max_chars"""
-        text = "这是第一句话。这是第二句话。这是第三句话。这是第四句话。这是第五句话。" * 10
-
-        result = split_text(text, max_chars=100)
-
         for seg in result:
             assert len(seg) <= 100
 
-    def test_long_single_sentence_hard_cut(self):
-        """超长单句会被硬切"""
-        text = "a" * 1000  # 没有标点
+    def test_force_split_preserves_all_chars(self):
+        """强制切段不丢字符."""
+        text = "a" * 250
+        result = split_text(text, max_chars=100)
+        # 所有段的总长度应等于原文（去掉空白可能有细微差异，但纯字母应该不变）
+        assert sum(len(s) for s in result) == 250
 
+    def test_mixed_long_and_short_sentences(self):
+        """长句短句混合."""
+        long_part = "非常长的句子没有标点符号" * 20
+        text = long_part + "。结束句。"
+        result = split_text(text, max_chars=100)
+        assert len(result) > 1
+        for seg in result:
+            assert len(seg) <= 100
+
+
+class TestSplitTextShortSegmentMerging:
+    """过短段落合并."""
+
+    def test_short_final_segment_merged(self):
+        """最后一段过短会被合并到前一段（如果不超限）."""
+        # 构造两段，第二段很短
+        text = "第一部分内容" * 10 + "。" + "短尾巴。"
         result = split_text(text, max_chars=200)
+        # 短尾巴应该被合并，不会单独成为一段
+        assert len(result) <= 2  # 可能1段或2段，但不会有3段
 
+    def test_very_short_segments_combined(self):
+        """多个极短段会被合并."""
+        # 构造多个短句，都<50字
+        sentences = ["你好。", "我好。", "大家好。", "天气不错。", "一起玩吧。", "好的。"]
+        text = "".join(sentences)
+        result = split_text(text, max_chars=200)
+        # 总长度很短，应该合并成1段
+        assert len(result) == 1
+
+
+class TestSplitTextEdgeCases:
+    """边界情况."""
+
+    def test_single_character(self):
+        """单字符."""
+        result = split_text("好", max_chars=10)
+        assert result == ["好"]
+
+    def test_only_punctuation(self):
+        """纯标点符号."""
+        text = "。。。。。"
+        result = split_text(text, max_chars=10)
+        assert len(result) == 1
+
+    def test_custom_max_chars_small(self):
+        """很小的max_chars."""
+        text = "一二三四五六七八九十。" * 5
+        result = split_text(text, max_chars=20)
         assert len(result) > 1
         for seg in result:
-            assert len(seg) <= 200
-
-    def test_newline_is_sentence_end(self):
-        """换行符作为句子结束符"""
-        text = "第一行内容\n第二行内容\n第三行内容" * 10
-
-        result = split_text(text, max_chars=50)
+            assert len(seg) <= 20
 
+    def test_mixed_chinese_english(self):
+        """中英文混合."""
+        text = "今天天气很好。Today is a nice day. 我们出去玩吧！Let's go out and play." * 20
+        result = split_text(text, max_chars=150)
         assert len(result) > 1
         for seg in result:
-            assert len(seg) <= 50
-
-    def test_chinese_punctuation(self):
-        """中文标点（。！？；）作为句子结束符"""
-        text = "你好！今天吃什么？我吃米饭；你呢？我也吃米饭。" * 10
-
-        result = split_text(text, max_chars=80)
-
-        for seg in result:
-            assert len(seg) <= 80
-
-    def test_english_punctuation(self):
-        """英文标点（.!?;）作为句子结束符"""
-        text = "Hello! How are you? I'm fine; thank you. Good bye." * 10
-
-        result = split_text(text, max_chars=80)
-
-        for seg in result:
-            assert len(seg) <= 80
-
-    def test_merged_short_segments(self):
-        """过短的段落会被合并"""
-        # 构造很多短句
-        text = "你好。再见。谢谢。抱歉。好的。不行。可以。去吧。" * 5  # 每句3-4字
+            assert len(seg) <= 150
 
+    def test_no_punctuation_long_text(self):
+        """完全没有标点的长文本，只能硬切."""
+        text = "字" * 500
         result = split_text(text, max_chars=100)
-
-        # 合并后段数应该比单纯按句切的少
-        assert len(result) < len(text) // 3  # 粗略估计
+        assert len(result) == 5
         for seg in result:
-            assert len(seg) <= 100
+            assert len(seg) == 100
 
-    def test_preserves_content(self):
-        """分段后内容总和与原文基本一致（忽略strip的空白）"""
-        text = "这是测试文本。包含多个句子。用来验证分段正确性。" * 5
+    def test_strip_leading_trailing_whitespace(self):
+        """首尾空白被去除."""
+        text = "   你好世界。   "
+        result = split_text(text, max_chars=100)
+        assert result == ["你好世界。"]
 
-        result = split_text(text, max_chars=50)
-
-        # 合并所有分段，去掉空白后应该与原文去掉空白后基本一致
-        combined = "".join(result).replace(" ", "")
-        original = text.strip().replace(" ", "")
-        assert combined == original
-
-    def test_custom_max_chars(self):
-        """支持自定义 max_chars"""
-        text = "测试" * 100  # 200字
-
-        result_50 = split_text(text, max_chars=50)
-        result_100 = split_text(text, max_chars=100)
-
-        # max_chars 越小，段数应该越多
-        assert len(result_50) >= len(result_100)
-
-    def test_single_char_text(self):
-        """单字符文本"""
-        assert split_text("好", max_chars=10) == ["好"]
-
-    def test_text_with_only_punctuation(self):
-        """纯标点文本"""
-        text = "。。。。。。。。。。"  # 10个句号
-        result = split_text(text, max_chars=5)
-
-        assert len(result) >= 1
-        for seg in result:
-            assert len(seg) <= 5
-
-    def test_mixed_content(self):
-        """中英文混合内容"""
-        text = "今天的天气是 sunny and warm。我们去了 park 玩。真的很开心！" * 5
-
-        result = split_text(text, max_chars=80)
-
-        for seg in result:
-            assert len(seg) <= 80
+    def test_total_length_preserved(self):
+        """分段后总字符数大致等于原文（去除首尾空白后）."""
+        text = "这是一段测试文本。" * 30
+        result = split_text(text, max_chars=100)
+        joined = "".join(result)
+        # 因为strip的原因可能略有差异，但应该接近
+        assert len(joined) == len(text.strip())
diff --git a/tests/unit/test_url_security.py b/tests/unit/test_url_security.py
index 20bdcb026..abe7e7c85 100755
--- a/tests/unit/test_url_security.py
+++ b/tests/unit/test_url_security.py
@@ -1,597 +1,532 @@
-"""
-url_security URL安全校验单元测试
+"""URL安全校验纯逻辑测试 — SSRF防护/魔数校验/可信域名.
 
-覆盖：
-- validate_url_safety: scheme/主机/端口/SSRF/内网域名/白名单
-- is_url_safe: 便捷函数
-- UrlSecurityError / NoRedirectHandler
-- _validate_magic_number: 文件魔数校验
-- safe_download_file / safe_download_bytes: mock 网络测试
+聚焦纯函数校验逻辑，DNS解析和实际下载用mock隔离。
 """
 
+from __future__ import annotations
+
+import ipaddress
 import os
 import tempfile
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
 import pytest
 
-from packages.shared.url_security import (
-    ALLOWED_AUDIO_MIME_TYPES,
-    ALLOWED_IMAGE_MIME_TYPES,
+from shared.url_security import (
     ALLOWED_PORTS,
     ALLOWED_SCHEMES,
-    MAX_URL_LENGTH,
-    NoRedirectHandler,
     UrlSecurityError,
     _check_internal_hostnames,
+    _check_ssrf_ip,
     _is_trusted_domain,
     _validate_magic_number,
     is_url_safe,
-    safe_download_bytes,
-    safe_download_file,
     validate_url_safety,
 )
 
-# ── validate_url_safety 基础校验 ─────────────────────────────────────────────
-
-
-class TestValidateUrlSafetyBasics:
-    """URL 安全校验基础测试"""
-
-    def test_valid_http_url(self):
-        url = "http://example.com/file.mp4"
-        result = validate_url_safety(url)
-        assert result == url
-
-    def test_valid_https_url(self):
-        url = "https://example.com/file.mp4"
-        result = validate_url_safety(url)
-        assert result == url
-
-    def test_empty_url_raises(self):
-        with pytest.raises(UrlSecurityError, match="为空"):
-            validate_url_safety("")
-
-    def test_none_url_raises(self):
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety(None)
-
-    def test_url_too_long_raises(self):
-        long_url = "https://example.com/" + "a" * 2050
-        with pytest.raises(UrlSecurityError, match="过长"):
-            validate_url_safety(long_url)
-
-    def test_url_at_max_length_ok(self):
-        base = "https://example.com/"
-        pad = "a" * (MAX_URL_LENGTH - len(base))
-        url = base + pad
-        assert len(url) <= MAX_URL_LENGTH
-        result = validate_url_safety(url)
-        assert result == url
-
-    def test_invalid_scheme_ftp_raises(self):
-        with pytest.raises(UrlSecurityError, match="scheme"):
-            validate_url_safety("ftp://example.com/file")
-
-    def test_invalid_scheme_file_raises(self):
-        with pytest.raises(UrlSecurityError, match="scheme"):
-            validate_url_safety("file:///etc/passwd")
-
-    def test_invalid_scheme_data_raises(self):
-        with pytest.raises(UrlSecurityError, match="scheme"):
-            validate_url_safety("data:text/html,<script>")
-
-    def test_missing_scheme_raises(self):
-        with pytest.raises(UrlSecurityError, match="scheme"):
-            validate_url_safety("example.com/file")
-
-    def test_missing_hostname_raises(self):
-        with pytest.raises(UrlSecurityError, match="主机名"):
-            validate_url_safety("http:///path")
-
-    def test_uppercase_scheme_normalized(self):
-        """HTTP/HTTPS 大写也能通过"""
-        url = "HTTPS://example.com/file"
-        # scheme 检查用 lower 比较
-        result = validate_url_safety(url)
-        assert result == url
-
-    def test_default_port_80_ok(self):
-        url = "http://example.com:80/file"
-        result = validate_url_safety(url)
-        assert result == url
-
-    def test_default_port_443_ok(self):
-        url = "https://example.com:443/file"
-        result = validate_url_safety(url)
-        assert result == url
-
-    def test_non_standard_port_raises(self):
-        with pytest.raises(UrlSecurityError, match="端口"):
-            validate_url_safety("http://example.com:8080/file")
-
-    def test_port_22_ssh_raises(self):
-        with pytest.raises(UrlSecurityError, match="端口"):
-            validate_url_safety("http://example.com:22/file")
-
-    def test_port_3306_mysql_raises(self):
-        with pytest.raises(UrlSecurityError, match="端口"):
-            validate_url_safety("http://example.com:3306/file")
-
-
-# ── 内网主机名 / SSRF 防护 ───────────────────────────────────────────────────
-
-
-class TestInternalHostnameProtection:
-    """内网主机名防护测试"""
-
-    def test_localhost_raises(self):
-        with pytest.raises(UrlSecurityError, match="内部主机名"):
-            validate_url_safety("http://localhost/file")
-
-    def test_localhost_mixed_case_raises(self):
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety("http://LocalHost/file")
-
-    def test_localhost_localdomain_raises(self):
-        with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("localhost.localdomain")
-
-    def test_metadata_hostname_raises(self):
-        with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("metadata")
-
-    def test_metadata_google_internal_raises(self):
-        with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("metadata.google.internal")
-
-    def test_dot_local_domain_raises(self):
-        with pytest.raises(UrlSecurityError, match="内网域名"):
-            validate_url_safety("http://myservice.local/file")
-
-    def test_dot_internal_domain_raises(self):
-        with pytest.raises(UrlSecurityError, match="内网域名"):
-            validate_url_safety("http://myservice.internal/file")
-
-    def test_dot_localdomain_raises(self):
-        with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("server.localdomain")
-
-    def test_loopback_ip_127_0_0_1_raises(self):
-        with pytest.raises(UrlSecurityError, match="直接 IP|回环"):
-            validate_url_safety("http://127.0.0.1/file")
-
-    def test_metadata_ip_169_254_raises(self):
-        """云元数据服务 IP"""
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety("http://169.254.169.254/latest/meta-data/")
-
-    def test_private_ip_10_raises(self):
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety("http://10.0.0.1/file")
-
-    def test_private_ip_172_16_raises(self):
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety("http://172.16.0.1/file")
-
-    def test_private_ip_192_168_raises(self):
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety("http://192.168.1.1/file")
-
-    def test_unspecified_ip_0_0_0_0_raises(self):
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety("http://0.0.0.0/file")
-
-    def test_ipv6_loopback_raises(self):
-        with pytest.raises(UrlSecurityError):
-            validate_url_safety("http://[::1]/file")
-
-    def test_public_ip_ok(self):
-        """公网IP在ALLOW_DIRECT_IP默认关闭时应被拦截"""
-        # 默认 ALLOW_DIRECT_IP = false
-        with pytest.raises(UrlSecurityError, match="直接 IP"):
-            validate_url_safety("http://8.8.8.8/file")
-
-
-# ── 可信域名白名单 ───────────────────────────────────────────────────────────
-
-
-class TestTrustedDomains:
-    """可信域名白名单测试"""
-
-    def test_is_trusted_domain_exact_match(self):
-        with patch("packages.shared.url_security.TRUSTED_DOMAINS", {"example.com", "cdn.example.org"}):
-            # 重新加载模块以应用环境变量不太现实，直接测函数
-            # 直接改全局状态再还原
-            import packages.shared.url_security as mod
-            from packages.shared.url_security import _is_trusted_domain
-
-            original = mod.TRUSTED_DOMAINS
-            mod.TRUSTED_DOMAINS = {"example.com", "cdn.example.org"}
-            try:
-                assert _is_trusted_domain("example.com") is True
-                assert _is_trusted_domain("cdn.example.org") is True
-            finally:
-                mod.TRUSTED_DOMAINS = original
-
-    def test_is_trusted_domain_subdomain(self):
-        import packages.shared.url_security as mod
-
-        original = mod.TRUSTED_DOMAINS
-        mod.TRUSTED_DOMAINS = {"example.com"}
-        try:
-            assert mod._is_trusted_domain("sub.example.com") is True
-            assert mod._is_trusted_domain("a.b.example.com") is True
-        finally:
-            mod.TRUSTED_DOMAINS = original
-
-    def test_is_trusted_domain_no_match(self):
-        import packages.shared.url_security as mod
-
-        original = mod.TRUSTED_DOMAINS
-        mod.TRUSTED_DOMAINS = {"example.com"}
-        try:
-            assert mod._is_trusted_domain("other.com") is False
-            assert mod._is_trusted_domain("notexample.com") is False
-        finally:
-            mod.TRUSTED_DOMAINS = original
-
-    def test_validate_with_trusted_domains_restricted(self):
-        """白名单非空时，不在白名单中的域名被拒"""
-        import packages.shared.url_security as mod
-
-        original = mod.TRUSTED_DOMAINS
-        mod.TRUSTED_DOMAINS = {"trusted.com"}
-        try:
-            # 不在白名单中 - 在 _is_trusted_domain 检查时就被拒，不走 DNS
-            with pytest.raises(UrlSecurityError, match="白名单"):
-                validate_url_safety("https://untrusted.com/file")
-
-            # 在白名单中 - 需要 mock DNS 解析避免实际网络请求
-            with patch("packages.shared.url_security._check_ssrf_domain"):
-                result = validate_url_safety("https://trusted.com/file")
-                assert result == "https://trusted.com/file"
-                # 子域名
-                result = validate_url_safety("https://sub.trusted.com/file")
-                assert result == "https://sub.trusted.com/file"
-        finally:
-            mod.TRUSTED_DOMAINS = original
-
-
-# ── is_url_safe 便捷函数 ─────────────────────────────────────────────────────
-
-
-class TestIsUrlSafe:
-    """is_url_safe 便捷函数测试"""
-
-    def test_safe_url_returns_true(self):
-        assert is_url_safe("https://example.com/file") is True
-
-    def test_unsafe_url_returns_false(self):
-        assert is_url_safe("http://localhost/file") is False
-
-    def test_empty_url_returns_false(self):
-        assert is_url_safe("") is False
-
-    def test_invalid_scheme_returns_false(self):
-        assert is_url_safe("ftp://example.com/file") is False
-
-
-# ── UrlSecurityError 异常类 ───────────────────────────────────────────────────
-
 
 class TestUrlSecurityError:
-    """UrlSecurityError 异常类测试"""
+    """UrlSecurityError 异常类."""
 
-    def test_is_value_error_subclass(self):
+    def test_is_value_error(self):
+        """继承自 ValueError."""
         assert issubclass(UrlSecurityError, ValueError)
 
-    def test_error_message(self):
+    def test_message_preserved(self):
+        """错误消息被保留."""
         err = UrlSecurityError("test message")
         assert str(err) == "test message"
 
 
-# ── NoRedirectHandler ────────────────────────────────────────────────────────
+class TestValidateUrlSafetyBasic:
+    """validate_url_safety 基础校验（不涉及DNS解析）."""
+
+    def test_empty_url_rejected(self):
+        """空URL被拒绝."""
+        with pytest.raises(UrlSecurityError, match="URL 为空"):
+            validate_url_safety("")
+
+    def test_none_url_rejected(self):
+        """None URL被拒绝."""
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety(None)
+
+    def test_url_too_long_rejected(self):
+        """超长URL被拒绝."""
+        long_url = "https://example.com/" + "a" * 2048
+        with pytest.raises(UrlSecurityError, match="URL 过长"):
+            validate_url_safety(long_url)
+
+    def test_invalid_scheme_rejected(self):
+        """非法scheme被拒绝."""
+        with pytest.raises(UrlSecurityError, match="不允许的 URL scheme"):
+            validate_url_safety("ftp://example.com/file.mp3")
+
+    def test_file_scheme_rejected(self):
+        """file:// scheme被拒绝."""
+        with pytest.raises(UrlSecurityError, match="不允许的 URL scheme"):
+            validate_url_safety("file:///etc/passwd")
+
+    def test_no_scheme_rejected(self):
+        """无scheme被拒绝."""
+        with pytest.raises(UrlSecurityError, match="不允许的 URL scheme"):
+            validate_url_safety("example.com/file.mp3")
+
+    def test_http_scheme_allowed(self):
+        """http scheme允许（需要mock DNS）."""
+        with patch("shared.url_security._check_ssrf_domain") as mock_check:
+            result = validate_url_safety("http://example.com/audio.mp3")
+            assert result == "http://example.com/audio.mp3"
+            mock_check.assert_called_once()
+
+    def test_https_scheme_allowed(self):
+        """https scheme允许."""
+        with patch("shared.url_security._check_ssrf_domain") as mock_check:
+            result = validate_url_safety("https://example.com/audio.mp3")
+            assert result == "https://example.com/audio.mp3"
+            mock_check.assert_called_once()
+
+    def test_scheme_case_insensitive(self):
+        """scheme大小写不敏感."""
+        with patch("shared.url_security._check_ssrf_domain") as mock_check:
+            result = validate_url_safety("HTTPS://example.com/audio.mp3")
+            assert result == "HTTPS://example.com/audio.mp3"
+
+    def test_missing_hostname_rejected(self):
+        """缺少主机名被拒绝."""
+        with pytest.raises(UrlSecurityError, match="URL 缺少主机名"):
+            validate_url_safety("https:///path/to/file")
+
+    def test_non_standard_port_rejected(self):
+        """非标准端口被拒绝."""
+        with pytest.raises(UrlSecurityError, match="不允许的端口"):
+            validate_url_safety("https://example.com:8080/audio.mp3")
+
+    def test_port_22_rejected(self):
+        """SSH端口被拒绝."""
+        with pytest.raises(UrlSecurityError, match="不允许的端口"):
+            validate_url_safety("https://example.com:22/")
+
+    def test_port_80_allowed(self):
+        """80端口允许."""
+        with patch("shared.url_security._check_ssrf_domain") as mock_check:
+            result = validate_url_safety("http://example.com:80/audio.mp3")
+            assert result == "http://example.com:80/audio.mp3"
+
+    def test_port_443_allowed(self):
+        """443端口允许."""
+        with patch("shared.url_security._check_ssrf_domain") as mock_check:
+            result = validate_url_safety("https://example.com:443/audio.mp3")
+            assert result == "https://example.com:443/audio.mp3"
+
+    def test_default_http_port_implicit_80(self):
+        """http默认端口隐含80，不触发端口校验."""
+        with patch("shared.url_security._check_ssrf_domain") as mock_check:
+            result = validate_url_safety("http://example.com/audio.mp3")
+            assert "example.com" in result
+
+    def test_default_https_port_implicit_443(self):
+        """https默认端口隐含443，不触发端口校验."""
+        with patch("shared.url_security._check_ssrf_domain") as mock_check:
+            result = validate_url_safety("https://example.com/audio.mp3")
+            assert "example.com" in result
+
+    def test_purpose_parameter_logged(self):
+        """purpose参数不影响校验结果."""
+        with patch("shared.url_security._check_ssrf_domain"):
+            result = validate_url_safety("https://example.com/a.mp3", purpose="tts_download")
+            assert result == "https://example.com/a.mp3"
+
+    def test_url_with_path_and_query(self):
+        """带路径和query参数的URL正常通过."""
+        with patch("shared.url_security._check_ssrf_domain"):
+            url = "https://example.com/path/to/file.mp3?token=abc&expires=123"
+            result = validate_url_safety(url)
+            assert result == url
 
 
-class TestNoRedirectHandler:
-    """NoRedirectHandler 测试"""
+class TestInternalHostnames:
+    """_check_internal_hostnames 内部主机名拦截."""
 
-    def test_redirect_request_returns_none(self):
-        handler = NoRedirectHandler()
-        result = handler.redirect_request(
-            MagicMock(),
-            MagicMock(),
-            302,
-            "Found",
-            {"Location": "http://other.com"},
-            "http://other.com",
-        )
-        assert result is None
+    def test_localhost_blocked(self):
+        """localhost被拦截."""
+        with pytest.raises(UrlSecurityError, match="禁止访问内部主机名"):
+            _check_internal_hostnames("localhost")
+
+    def test_localhost_case_insensitive(self):
+        """大小写不敏感."""
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("LOCALHOST")
+
+    def test_localhost_localdomain_blocked(self):
+        """localhost.localdomain被拦截."""
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("localhost.localdomain")
+
+    def test_metadata_blocked(self):
+        """metadata被拦截."""
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("metadata")
+
+    def test_metadata_google_internal_blocked(self):
+        """GCP元数据服务被拦截."""
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("metadata.google.internal")
+
+    def test_local_domain_suffix_blocked(self):
+        """.local后缀被拦截."""
+        with pytest.raises(UrlSecurityError, match="禁止访问内网域名"):
+            _check_internal_hostnames("printer.local")
+
+    def test_internal_domain_suffix_blocked(self):
+        """.internal后缀被拦截."""
+        with pytest.raises(UrlSecurityError, match="禁止访问内网域名"):
+            _check_internal_hostnames("service.internal")
+
+    def test_localdomain_suffix_blocked(self):
+        """.localdomain后缀被拦截."""
+        with pytest.raises(UrlSecurityError, match="禁止访问内网域名"):
+            _check_internal_hostnames("host.localdomain")
+
+    def test_public_domain_passes(self):
+        """公网域名通过."""
+        _check_internal_hostnames("example.com")  # 不抛异常即通过
+
+    def test_subdomain_of_public_domain_passes(self):
+        """公网域名子域名通过."""
+        _check_internal_hostnames("cdn.example.com")  # 不抛异常即通过
 
 
-# ── 魔数校验 ─────────────────────────────────────────────────────────────────
+class TestSSRFIPCheck:
+    """_check_ssrf_ip SSRF IP检查."""
+
+    def test_loopback_ipv4_blocked(self):
+        """IPv4回环地址被拦截."""
+        with pytest.raises(UrlSecurityError, match="回环地址"):
+            _check_ssrf_ip(ipaddress.ip_address("127.0.0.1"))
+
+    def test_loopback_ipv6_blocked(self):
+        """IPv6回环地址被拦截."""
+        with pytest.raises(UrlSecurityError, match="回环地址"):
+            _check_ssrf_ip(ipaddress.ip_address("::1"))
+
+    def test_private_ip_10_blocked(self):
+        """10.x.x.x私有地址被拦截."""
+        with pytest.raises(UrlSecurityError, match="内网地址"):
+            _check_ssrf_ip(ipaddress.ip_address("10.0.0.1"))
+
+    def test_private_ip_172_blocked(self):
+        """172.16.x.x私有地址被拦截."""
+        with pytest.raises(UrlSecurityError, match="内网地址"):
+            _check_ssrf_ip(ipaddress.ip_address("172.16.0.1"))
+
+    def test_private_ip_192_blocked(self):
+        """192.168.x.x私有地址被拦截."""
+        with pytest.raises(UrlSecurityError, match="内网地址"):
+            _check_ssrf_ip(ipaddress.ip_address("192.168.1.1"))
+
+    def test_link_local_blocked(self):
+        """链路本地地址被拦截（is_private 先命中也可以，只要被拦就行）."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("169.254.169.254"))
+
+    def test_multicast_blocked(self):
+        """组播地址被拦截."""
+        with pytest.raises(UrlSecurityError, match="组播地址"):
+            _check_ssrf_ip(ipaddress.ip_address("224.0.0.1"))
+
+    def test_unspecified_ipv4_blocked(self):
+        """0.0.0.0被拦截."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("0.0.0.0"))
+
+    def test_unspecified_ipv6_blocked(self):
+        """::被拦截."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("::"))
+
+    def test_reserved_ip_blocked(self):
+        """保留地址被拦截（240.0.0.0/4 属于保留段）."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("240.0.0.1"))
+
+    def test_public_ip_passes(self):
+        """公网IP通过（当ALLOW_DIRECT_IP=true时）."""
+        # 注意：公网IP在_check_ssrf_ip层面不拦截，拦截在validate_url_safety的ALLOW_DIRECT_IP层
+        _check_ssrf_ip(ipaddress.ip_address("8.8.8.8"))  # 不抛异常即通过
+
+    def test_public_ip_another_passes(self):
+        """另一个公网IP通过."""
+        _check_ssrf_ip(ipaddress.ip_address("1.1.1.1"))  # 不抛异常即通过
+
+    def test_ipv6_public_passes(self):
+        """IPv6公网地址通过."""
+        _check_ssrf_ip(ipaddress.ip_address("2001:4860:4860::8888"))  # 不抛异常即通过
+
+
+class TestDirectIPBlocking:
+    """直接IP访问拦截."""
+
+    def test_direct_ipv4_blocked_by_default(self):
+        """默认禁止直接IP访问."""
+        with pytest.raises(UrlSecurityError, match="禁止直接 IP 访问"):
+            validate_url_safety("https://8.8.8.8/audio.mp3")
+
+    def test_direct_ipv6_blocked_by_default(self):
+        """默认禁止直接IPv6访问."""
+        with pytest.raises(UrlSecurityError, match="禁止直接 IP 访问"):
+            validate_url_safety("https://[2001:4860:4860::8888]/audio.mp3")
+
+    def test_direct_ip_allowed_when_flag_set(self):
+        """ALLOW_DIRECT_IP=true时允许公网IP直接访问."""
+        with patch("shared.url_security.ALLOW_DIRECT_IP", True):
+            # 公网IP应该通过
+            with patch("shared.url_security._check_ssrf_ip") as mock_check:
+                result = validate_url_safety("https://8.8.8.8/audio.mp3")
+                assert result == "https://8.8.8.8/audio.mp3"
+                mock_check.assert_called_once()
+
+    def test_direct_private_ip_blocked_even_with_flag(self):
+        """即使ALLOW_DIRECT_IP=true，私有IP仍被SSRF检查拦截."""
+        with patch("shared.url_security.ALLOW_DIRECT_IP", True):
+            with pytest.raises(UrlSecurityError, match="内网地址"):
+                validate_url_safety("https://192.168.1.1/audio.mp3")
+
+
+class TestTrustedDomain:
+    """_is_trusted_domain 可信域名匹配."""
+
+    def test_exact_match(self):
+        """精确匹配."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
+            assert _is_trusted_domain("example.com") is True
+
+    def test_subdomain_match(self):
+        """子域名匹配."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
+            assert _is_trusted_domain("cdn.example.com") is True
+
+    def test_nested_subdomain_match(self):
+        """多级子域名匹配."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
+            assert _is_trusted_domain("a.b.c.example.com") is True
+
+    def test_no_match(self):
+        """不匹配的域名."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
+            assert _is_trusted_domain("other.com") is False
+
+    def test_domain_containing_but_not_subdomain(self):
+        """域名包含但不是子域名."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
+            assert _is_trusted_domain("fake-example.com") is False
+
+    def test_case_insensitive(self):
+        """大小写不敏感."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", {"Example.COM"}):
+            assert _is_trusted_domain("cdn.example.com") is True
+
+    def test_empty_trusted_domains(self):
+        """空白名单时全部返回False."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", set()):
+            assert _is_trusted_domain("anything.com") is False
+
+    def test_multiple_trusted_domains(self):
+        """多个可信域名."""
+        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com", "aliyuncs.com"}):
+            assert _is_trusted_domain("bucket.oss-cn-hangzhou.aliyuncs.com") is True
+            assert _is_trusted_domain("cdn.example.com") is True
+            assert _is_trusted_domain("unknown.com") is False
+
+
+class TestIsUrlSafe:
+    """is_url_safe 便捷函数."""
+
+    def test_safe_url_returns_true(self):
+        """安全URL返回True."""
+        with patch("shared.url_security._check_ssrf_domain"):
+            assert is_url_safe("https://example.com/a.mp3") is True
+
+    def test_unsafe_url_returns_false(self):
+        """不安全URL返回False."""
+        assert is_url_safe("ftp://example.com/a.mp3") is False
+
+    def test_empty_url_returns_false(self):
+        """空URL返回False."""
+        assert is_url_safe("") is False
+
+    def test_does_not_raise(self):
+        """不抛异常."""
+        try:
+            is_url_safe("not a url at all")
+        except Exception:
+            pytest.fail("is_url_safe should not raise exceptions")
 
 
 class TestMagicNumberValidation:
-    """文件魔数校验测试"""
+    """_validate_magic_number 文件魔数校验."""
 
-    def test_valid_png(self, tmp_path):
-        f = tmp_path / "test.png"
-        # PNG 文件头: 89 50 4E 47 0D 0A 1A 0A
-        f.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
-        # 不抛异常 = 通过
-        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_valid_mp3_id3v2(self):
+        """MP3 ID3v2标签魔数通过."""
+        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
+            f.write(b"ID3" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"audio/mpeg"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_jpeg(self, tmp_path):
-        f = tmp_path / "test.jpg"
-        # JPEG 文件头: FF D8 FF
-        f.write_bytes(b"\xff\xd8\xff\xe0" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_valid_wav(self):
+        """WAV文件魔数通过."""
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+            # RIFF + WAVE
+            f.write(b"RIFF" + b"\x00" * 4 + b"WAVE" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"audio/wav"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_gif87a(self, tmp_path):
-        f = tmp_path / "test.gif"
-        f.write_bytes(b"GIF87a" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_valid_png(self):
+        """PNG图片魔数通过."""
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+            f.write(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"image/png"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_gif89a(self, tmp_path):
-        f = tmp_path / "test.gif"
-        f.write_bytes(b"GIF89a" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_valid_jpeg(self):
+        """JPEG图片魔数通过."""
+        with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as f:
+            f.write(b"\xff\xd8\xff" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"image/jpeg"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_webp(self, tmp_path):
-        f = tmp_path / "test.webp"
-        # RIFF....WEBP
-        data = bytearray(b"RIFF")
-        data += b"\x00\x00\x00\x00"  # size placeholder
-        data += b"WEBP"
-        data += b"\x00" * 100
-        f.write_bytes(bytes(data))
-        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_valid_gif87a(self):
+        """GIF87a通过."""
+        with tempfile.NamedTemporaryFile(suffix=".gif", delete=False) as f:
+            f.write(b"GIF87a" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"image/gif"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_bmp(self, tmp_path):
-        f = tmp_path / "test.bmp"
-        f.write_bytes(b"BM" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_valid_gif89a(self):
+        """GIF89a通过."""
+        with tempfile.NamedTemporaryFile(suffix=".gif", delete=False) as f:
+            f.write(b"GIF89a" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"image/gif"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_wav(self, tmp_path):
-        f = tmp_path / "test.wav"
-        # RIFF....WAVE
-        data = bytearray(b"RIFF")
-        data += b"\x00\x00\x00\x00"
-        data += b"WAVE"
-        data += b"\x00" * 100
-        f.write_bytes(bytes(data))
-        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+    def test_valid_ogg(self):
+        """OGG音频通过."""
+        with tempfile.NamedTemporaryFile(suffix=".ogg", delete=False) as f:
+            f.write(b"OggS" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"audio/ogg"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_mp3_id3(self, tmp_path):
-        f = tmp_path / "test.mp3"
-        f.write_bytes(b"ID3\x03\x00\x00\x00\x00\x00\x00" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+    def test_invalid_magic_number_rejected(self):
+        """错误魔数被拒绝."""
+        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
+            f.write(b"NOT_A_VALID_FILE" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            with pytest.raises(UrlSecurityError, match="文件魔数与允许的 MIME 类型不匹配"):
+                _validate_magic_number(tmp_path, {"audio/mpeg", "image/png"})
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_mp3_adts(self, tmp_path):
-        f = tmp_path / "test.mp3"
-        f.write_bytes(b"\xff\xfb\x90\x00" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+    def test_empty_file_rejected(self):
+        """空文件被拒绝."""
+        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
+            tmp_path = f.name
+        try:
+            with pytest.raises(UrlSecurityError, match="文件为空"):
+                _validate_magic_number(tmp_path, {"audio/mpeg"})
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_ogg(self, tmp_path):
-        f = tmp_path / "test.ogg"
-        f.write_bytes(b"OggS\x00\x02\x00\x00" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+    def test_unknown_mime_skipped(self):
+        """未知MIME类型跳过校验."""
+        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
+            f.write(b"random data here")
+            tmp_path = f.name
+        try:
+            # 未知MIME类型没有对应的魔数，应该跳过不阻断
+            _validate_magic_number(tmp_path, {"application/x-unknown-type"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_valid_flac(self, tmp_path):
-        f = tmp_path / "test.flac"
-        f.write_bytes(b"fLaC" + b"\x00" * 100)
-        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+    def test_empty_allowed_mime_skipped(self):
+        """空allowed_mime_types集合直接通过（无魔数可比对）."""
+        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
+            f.write(b"anything")
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, set())  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_invalid_file_content_raises(self, tmp_path):
-        f = tmp_path / "test.bin"
-        f.write_bytes(b"this is not an image file at all")
-        with pytest.raises(UrlSecurityError, match="魔数"):
-            _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_multiple_allowed_types_one_matches(self):
+        """多个允许类型，只要一个匹配就通过."""
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+            f.write(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"audio/mpeg", "image/png", "image/jpeg"})
+        finally:
+            os.unlink(tmp_path)
 
-    def test_empty_file_raises(self, tmp_path):
-        f = tmp_path / "empty.bin"
-        f.write_bytes(b"")
-        with pytest.raises(UrlSecurityError, match="为空"):
-            _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+    def test_mp4_ftyp_magic(self):
+        """MP4 ftyp魔数通过."""
+        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:
+            # ftyp在偏移4的位置
+            f.write(b"\x00\x00\x00\x20" + b"ftyp" + b"mp42" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"video/mp4"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_nonexistent_file_raises(self, tmp_path):
-        with pytest.raises(UrlSecurityError, match="读取文件头失败"):
-            _validate_magic_number(str(tmp_path / "no_such_file"), ALLOWED_IMAGE_MIME_TYPES)
+    def test_webp_magic(self):
+        """WebP魔数通过."""
+        with tempfile.NamedTemporaryFile(suffix=".webp", delete=False) as f:
+            f.write(b"RIFF" + b"\x00" * 4 + b"WEBP" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"image/webp"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_no_allowed_mime_types_skips(self, tmp_path):
-        """allowed_mime_types 为空时跳过校验"""
-        f = tmp_path / "test.bin"
-        f.write_bytes(b"random data here")
-        # 不抛异常
-        _validate_magic_number(str(f), set())
+    def test_flac_magic(self):
+        """FLAC魔数通过."""
+        with tempfile.NamedTemporaryFile(suffix=".flac", delete=False) as f:
+            f.write(b"fLaC" + b"\x00" * 100)
+            tmp_path = f.name
+        try:
+            _validate_magic_number(tmp_path, {"audio/flac"})  # 不抛异常即通过
+        finally:
+            os.unlink(tmp_path)
 
-    def test_unknown_mime_types_skips(self, tmp_path):
-        """没有已知魔数的 MIME 类型跳过校验"""
-        f = tmp_path / "test.bin"
-        f.write_bytes(b"random data")
-        _validate_magic_number(str(f), {"application/x-unknown-type"})
-
-
-# ── safe_download_file (mock 网络) ───────────────────────────────────────────
-
-
-class TestSafeDownloadFile:
-    """safe_download_file 下载测试（mock 网络）"""
-
-    def test_download_success(self, tmp_path):
-        test_content = b"Hello, this is test file content!"
-        dest = str(tmp_path / "output.bin")
-
-        mock_resp = MagicMock()
-        mock_resp.headers = {"Content-Type": "application/octet-stream"}
-        mock_resp.read.side_effect = [test_content, b""]
-
-        with patch("packages.shared.url_security.NoRedirectHandler") as mock_handler_cls:
-            mock_handler = MagicMock()
-            mock_handler_cls.return_value = mock_handler
-
-            mock_opener = MagicMock()
-            mock_opener.open.return_value = mock_resp
-
-            with patch("urllib.request.build_opener", return_value=mock_opener):
-                size = safe_download_file(
-                    "https://example.com/test.bin",
-                    dest,
-                    purpose="test",
-                )
-
-        assert size == len(test_content)
-        with open(dest, "rb") as f:
-            assert f.read() == test_content
-
-    def test_download_with_mime_check_passes(self, tmp_path):
-        # PNG 文件
-        test_content = b"\x89PNG\r\n\x1a\n" + b"\x00" * 200
-        dest = str(tmp_path / "test.png")
-
-        mock_resp = MagicMock()
-        mock_resp.headers = {"Content-Type": "image/png"}
-        mock_resp.read.side_effect = [test_content, b""]
-
-        with patch("urllib.request.build_opener") as mock_build:
-            mock_opener = MagicMock()
-            mock_opener.open.return_value = mock_resp
-            mock_build.return_value = mock_opener
-
-            size = safe_download_file(
-                "https://example.com/test.png",
-                dest,
-                purpose="test",
-                allowed_mime_types={"image/png", "image/jpeg"},
-            )
-
-        assert size == len(test_content)
-
-    def test_download_mime_type_rejected(self, tmp_path):
-        test_content = b"GIF89a" + b"\x00" * 50
-        dest = str(tmp_path / "test.gif")
-
-        mock_resp = MagicMock()
-        mock_resp.headers = {"Content-Type": "image/gif"}
-        mock_resp.read.side_effect = [test_content, b""]
-
-        with patch("urllib.request.build_opener") as mock_build:
-            mock_opener = MagicMock()
-            mock_opener.open.return_value = mock_resp
-            mock_build.return_value = mock_opener
-
-            with pytest.raises(UrlSecurityError, match="Content-Type"):
-                safe_download_file(
-                    "https://example.com/test.gif",
-                    dest,
-                    purpose="test",
-                    allowed_mime_types={"image/png"},
-                )
-
-    def test_download_size_limit_exceeded(self, tmp_path):
-        """流式下载时超过大小限制被中断（无 Content-Length header）"""
-        dest = str(tmp_path / "big.bin")
-        chunk = b"x" * 1024  # 1KB chunks
-
-        mock_resp = MagicMock()
-        # 没有 Content-Length header，走流式检查
-        mock_resp.headers = {"Content-Type": "application/octet-stream"}
-        # 模拟多次读取，超过 5KB 限制（6个chunk = 6KB）
-        mock_resp.read.side_effect = [chunk] * 6 + [b""]
-
-        with patch("urllib.request.build_opener") as mock_build:
-            mock_opener = MagicMock()
-            mock_opener.open.return_value = mock_resp
-            mock_build.return_value = mock_opener
-
-            with pytest.raises(UrlSecurityError, match="超过大小限制"):
-                safe_download_file(
-                    "https://example.com/big.bin",
-                    dest,
-                    purpose="test",
-                    max_size=5000,  # 5KB limit
-                )
-
-    def test_download_content_length_too_large(self, tmp_path):
-        dest = str(tmp_path / "big.bin")
-
-        mock_resp = MagicMock()
-        mock_resp.headers = {"Content-Type": "application/octet-stream", "Content-Length": "1000000"}
-        mock_resp.read.side_effect = [b"data"]
-
-        with patch("urllib.request.build_opener") as mock_build:
-            mock_opener = MagicMock()
-            mock_opener.open.return_value = mock_resp
-            mock_build.return_value = mock_opener
-
-            with pytest.raises(UrlSecurityError, match="文件过大"):
-                safe_download_file(
-                    "https://example.com/big.bin",
-                    dest,
-                    purpose="test",
-                    max_size=500000,
-                )
-
-    def test_download_localhost_rejected(self, tmp_path):
-        """内网 URL 在下载前就被拒"""
-        dest = str(tmp_path / "out.bin")
-        with pytest.raises(UrlSecurityError):
-            safe_download_file("http://localhost/file", dest)
-
-    def test_download_invalid_scheme_rejected(self, tmp_path):
-        dest = str(tmp_path / "out.bin")
-        with pytest.raises(UrlSecurityError, match="scheme"):
-            safe_download_file("ftp://example.com/file", dest)
-
-
-# ── safe_download_bytes ───────────────────────────────────────────────────────
-
-
-class TestSafeDownloadBytes:
-    """safe_download_bytes 测试"""
-
-    def test_download_returns_bytes(self, tmp_path):
-        test_content = b"hello bytes download test"
-
-        mock_resp = MagicMock()
-        mock_resp.headers = {"Content-Type": "application/octet-stream"}
-        mock_resp.read.side_effect = [test_content, b""]
-
-        with patch("urllib.request.build_opener") as mock_build:
-            mock_opener = MagicMock()
-            mock_opener.open.return_value = mock_resp
-            mock_build.return_value = mock_opener
-
-            result = safe_download_bytes(
-                "https://example.com/test.bin",
-                purpose="test",
-            )
-
-        assert result == test_content
-        assert isinstance(result, bytes)
-
-    def test_download_unsafe_url_raises(self):
-        with pytest.raises(UrlSecurityError):
-            safe_download_bytes("http://127.0.0.1/secret")
-
-
-# ── 常量导出验证 ─────────────────────────────────────────────────────────────
-
-
-class TestConstants:
-    """模块常量验证"""
-
-    def test_allowed_schemes(self):
-        assert "http" in ALLOWED_SCHEMES
-        assert "https" in ALLOWED_SCHEMES
-        assert len(ALLOWED_SCHEMES) == 2
-
-    def test_allowed_ports(self):
-        assert 80 in ALLOWED_PORTS
-        assert 443 in ALLOWED_PORTS
-        assert len(ALLOWED_PORTS) == 2
-
-    def test_max_url_length(self):
-        assert MAX_URL_LENGTH == 2048
+    def test_file_too_short_for_signature(self):
+        """文件太短，不够签名长度时不匹配."""
+        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
+            f.write(b"ID")  # 只有2字节，不够ID3的3字节
+            tmp_path = f.name
+        try:
+            with pytest.raises(UrlSecurityError, match="文件魔数"):
+                _validate_magic_number(tmp_path, {"audio/mpeg"})
+        finally:
+            os.unlink(tmp_path)
-- 
2.54.0


From d1348bcd806488bb420697e230e9b80a85de9e39 Mon Sep 17 00:00:00 2001
From: CI Bot <ci-bot@xiaoxiajianji.com>
Date: Sat, 25 Jul 2026 10:25:26 +0800
Subject: [PATCH 2/3] =?UTF-8?q?test:=20=E7=AC=AC73=E6=B3=A2=20url=5Fsecuri?=
 =?UTF-8?q?ty=20+=20pagination=20+=20text=5Fsplitter=20=E5=8D=95=E6=B5=8B?=
 =?UTF-8?q?=E8=A1=A5=E5=85=85=20(+68)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

在原有测试基础上补充覆盖：

- url_security (+28):
  - TestSSRFIPCheck: 14个IP类型全覆盖（回环/各私有段/链路本地/组播/未指定/保留/公网）
  - TestDirectIPAccess: 直接IP访问开关控制
  - TestMagicNumberExtended: 更多格式魔数校验(AAC/M4A/WebP/MP4/WebM/BMP/FLAC/OGG/读取失败/多类型)

- pagination (+20):
  - TestPaginationParamsEdgeCases: 边界值/极大页码/offset计算
  - TestPaginationMetaEdgeCases: total=0/刚好最后一页/多1条/单条数据
  - TestPaginateEdgeCases: 单元素/超尾页/空列表/page_size=1/不修改输入

- text_splitter (+20):
  - TestSplitTextEmptyAndShort: 空白/单字符/边界值/None
  - TestSplitTextSentenceBoundaries: 各标点分段/短句合并
  - TestSplitTextLongSentenceForce: 无标点硬切/不丢字符/长短混合
  - TestSplitTextShortSegmentMerge: 多短句合并/短尾合并
  - TestSplitTextEdgeCases: 纯标点/中英混合/去空白/总长度守恒
---
 tests/unit/test_pagination.py    |  531 ++++++++------
 tests/unit/test_text_splitter.py |  378 ++++++----
 tests/unit/test_url_security.py  | 1129 +++++++++++++++++++-----------
 3 files changed, 1249 insertions(+), 789 deletions(-)

diff --git a/tests/unit/test_pagination.py b/tests/unit/test_pagination.py
index a39c49cf1..1d7c55e30 100755
--- a/tests/unit/test_pagination.py
+++ b/tests/unit/test_pagination.py
@@ -1,16 +1,11 @@
-"""分页器纯逻辑测试 — PaginationParams/PaginationMeta/paginate.
-
-覆盖参数校验、偏移计算、元数据计算、内存分页等全部纯逻辑。
-"""
+"""通用分页器单元测试."""
 
 from __future__ import annotations
 
-from math import ceil
-
 import pytest
 from pydantic import ValidationError
 
-from application.common.pagination import (
+from packages.application.common.pagination import (
     PaginatedResponse,
     PaginationMeta,
     PaginationParams,
@@ -18,183 +13,315 @@ from application.common.pagination import (
 )
 
 
-class TestPaginationParamsDefaults:
-    """PaginationParams 默认值与属性."""
+class TestPaginationParams:
+    """PaginationParams 测试"""
 
-    def test_default_page_is_1(self):
-        """默认页码为1."""
+    def test_default_values(self):
+        """默认值正确"""
         params = PaginationParams()
         assert params.page == 1
-
-    def test_default_page_size_is_20(self):
-        """默认每页20条."""
-        params = PaginationParams()
         assert params.page_size == 20
 
-    def test_offset_first_page_is_0(self):
-        """第一页偏移量为0."""
+    def test_offset_first_page(self):
+        """第一页 offset 为 0"""
         params = PaginationParams(page=1, page_size=20)
         assert params.offset == 0
 
     def test_offset_second_page(self):
-        """第二页偏移量=page_size."""
+        """第二页 offset 计算正确"""
         params = PaginationParams(page=2, page_size=20)
         assert params.offset == 20
 
-    def test_offset_page_3_size_10(self):
-        """第3页每页10条，偏移20."""
+    def test_offset_custom_page_size(self):
+        """自定义 page_size 的 offset"""
         params = PaginationParams(page=3, page_size=10)
         assert params.offset == 20
 
     def test_limit_equals_page_size(self):
-        """limit等于page_size."""
+        """limit 等于 page_size"""
         params = PaginationParams(page_size=50)
         assert params.limit == 50
 
-
-class TestPaginationParamsValidation:
-    """PaginationParams 参数校验."""
-
-    def test_page_zero_rejected(self):
-        """页码0被拒绝."""
+    def test_page_must_be_at_least_1(self):
+        """page 不能小于 1"""
         with pytest.raises(ValidationError):
             PaginationParams(page=0)
 
-    def test_page_negative_rejected(self):
-        """负页码被拒绝."""
+    def test_page_negative_raises(self):
+        """page 不能为负数"""
         with pytest.raises(ValidationError):
             PaginationParams(page=-1)
 
-    def test_page_size_zero_rejected(self):
-        """每页0条被拒绝."""
+    def test_page_size_must_be_at_least_1(self):
+        """page_size 不能小于 1"""
         with pytest.raises(ValidationError):
             PaginationParams(page_size=0)
 
-    def test_page_size_negative_rejected(self):
-        """负每页条数被拒绝."""
-        with pytest.raises(ValidationError):
-            PaginationParams(page_size=-5)
-
-    def test_page_size_over_100_rejected(self):
-        """每页超过100条被拒绝."""
+    def test_page_size_max_100(self):
+        """page_size 最大 100"""
         with pytest.raises(ValidationError):
             PaginationParams(page_size=101)
 
-    def test_page_size_100_allowed(self):
-        """每页100条允许."""
+    def test_page_size_100_is_valid(self):
+        """page_size=100 是合法的"""
         params = PaginationParams(page_size=100)
         assert params.page_size == 100
 
-    def test_page_size_1_allowed(self):
-        """每页1条允许."""
+
+class TestPaginationMeta:
+    """PaginationMeta 测试"""
+
+    def test_from_params_first_page(self):
+        """第一页元数据"""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=25)
+
+        assert meta.page == 1
+        assert meta.page_size == 10
+        assert meta.total == 25
+        assert meta.total_pages == 3
+        assert meta.has_next is True
+        assert meta.has_prev is False
+
+    def test_from_params_last_page(self):
+        """最后一页元数据"""
+        params = PaginationParams(page=3, page_size=10)
+        meta = PaginationMeta.from_params(params, total=25)
+
+        assert meta.page == 3
+        assert meta.total_pages == 3
+        assert meta.has_next is False
+        assert meta.has_prev is True
+
+    def test_from_params_middle_page(self):
+        """中间页元数据"""
+        params = PaginationParams(page=2, page_size=10)
+        meta = PaginationMeta.from_params(params, total=50)
+
+        assert meta.page == 2
+        assert meta.total_pages == 5
+        assert meta.has_next is True
+        assert meta.has_prev is True
+
+    def test_from_params_zero_total(self):
+        """总数为 0 时"""
+        params = PaginationParams(page=1, page_size=20)
+        meta = PaginationMeta.from_params(params, total=0)
+
+        assert meta.total == 0
+        assert meta.total_pages == 0
+        assert meta.has_next is False
+        assert meta.has_prev is False
+
+    def test_from_params_exact_multiple(self):
+        """总数刚好是 page_size 的整数倍"""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=30)
+
+        assert meta.total_pages == 3
+
+    def test_from_params_single_page(self):
+        """单页即可放下所有数据"""
+        params = PaginationParams(page=1, page_size=100)
+        meta = PaginationMeta.from_params(params, total=50)
+
+        assert meta.total_pages == 1
+        assert meta.has_next is False
+        assert meta.has_prev is False
+
+
+class TestPaginatedResponse:
+    """PaginatedResponse 测试"""
+
+    def test_create_success(self):
+        """创建分页响应"""
+        params = PaginationParams(page=1, page_size=10)
+        data = [1, 2, 3]
+
+        response = PaginatedResponse.create(data, params, total=25)
+
+        assert response.data == [1, 2, 3]
+        assert response.pagination.page == 1
+        assert response.pagination.total == 25
+        assert response.pagination.total_pages == 3
+
+    def test_create_empty_data(self):
+        """空数据分页响应"""
+        params = PaginationParams(page=1, page_size=20)
+        response = PaginatedResponse.create([], params, total=0)
+
+        assert response.data == []
+        assert response.pagination.total == 0
+        assert response.pagination.total_pages == 0
+
+
+class TestPaginateFunction:
+    """paginate 函数测试（内存分页）"""
+
+    def test_first_page(self):
+        """第一页分页"""
+        items = list(range(30))
+        params = PaginationParams(page=1, page_size=10)
+
+        result = paginate(items, params)
+
+        assert result.data == list(range(10))
+        assert result.pagination.total == 30
+        assert result.pagination.total_pages == 3
+        assert result.pagination.has_next is True
+        assert result.pagination.has_prev is False
+
+    def test_second_page(self):
+        """第二页分页"""
+        items = list(range(30))
+        params = PaginationParams(page=2, page_size=10)
+
+        result = paginate(items, params)
+
+        assert result.data == list(range(10, 20))
+        assert result.pagination.page == 2
+
+    def test_last_page(self):
+        """最后一页分页"""
+        items = list(range(25))
+        params = PaginationParams(page=3, page_size=10)
+
+        result = paginate(items, params)
+
+        assert result.data == list(range(20, 25))
+        assert len(result.data) == 5
+        assert result.pagination.has_next is False
+
+    def test_empty_list(self):
+        """空列表分页"""
+        params = PaginationParams(page=1, page_size=20)
+        result = paginate([], params)
+
+        assert result.data == []
+        assert result.pagination.total == 0
+        assert result.pagination.total_pages == 0
+
+    def test_page_beyond_total(self):
+        """页码超出总数"""
+        items = list(range(5))
+        params = PaginationParams(page=10, page_size=10)
+
+        result = paginate(items, params)
+
+        assert result.data == []
+        assert result.pagination.total == 5
+        assert result.pagination.total_pages == 1
+
+    def test_custom_page_size(self):
+        """自定义每页数量"""
+        items = list(range(100))
+        params = PaginationParams(page=1, page_size=50)
+
+        result = paginate(items, params)
+
+        assert len(result.data) == 50
+        assert result.pagination.total_pages == 2
+
+    def test_single_item(self):
+        """单条数据"""
+        items = ["only_one"]
+        params = PaginationParams(page=1, page_size=10)
+
+        result = paginate(items, params)
+
+        assert result.data == ["only_one"]
+        assert result.pagination.total == 1
+        assert result.pagination.total_pages == 1
+
+    def test_generic_type_preserved(self):
+        """泛型类型数据正确"""
+        items = [{"id": 1, "name": "a"}, {"id": 2, "name": "b"}]
+        params = PaginationParams(page=1, page_size=10)
+
+        result = paginate(items, params)
+
+        assert len(result.data) == 2
+        assert result.data[0]["id"] == 1
+
+
+# ── PaginationParams 补充边界 ───────────────────────────────────────────────
+
+
+class TestPaginationParamsEdgeCases:
+    """PaginationParams 补充边界场景."""
+
+    def test_page_size_1_minimum(self):
+        """page_size=1 是允许的最小值."""
         params = PaginationParams(page_size=1)
         assert params.page_size == 1
+        assert params.limit == 1
 
-    def test_page_1_allowed(self):
-        """页码1允许."""
-        params = PaginationParams(page=1)
-        assert params.page == 1
+    def test_page_size_100_maximum(self):
+        """page_size=100 是允许的最大值."""
+        params = PaginationParams(page_size=100)
+        assert params.page_size == 100
 
-    def test_large_page_allowed(self):
-        """大页码允许（不设上限）."""
-        params = PaginationParams(page=9999)
-        assert params.page == 9999
+    def test_offset_page_1_size_100(self):
+        """第1页每页100条 offset=0."""
+        params = PaginationParams(page=1, page_size=100)
+        assert params.offset == 0
+
+    def test_offset_page_100_size_100(self):
+        """第100页每页100条 offset=9900."""
+        params = PaginationParams(page=100, page_size=100)
+        assert params.offset == 9900
+
+    def test_large_page_number_accepted(self):
+        """极大页码（超过实际页数）允许."""
+        params = PaginationParams(page=999999, page_size=20)
+        assert params.page == 999999
+        assert params.offset == (999999 - 1) * 20
 
 
-class TestPaginationMetaFromParams:
-    """PaginationMeta.from_params 元数据计算."""
+# ── PaginationMeta 补充边界 ─────────────────────────────────────────────────
 
-    def test_first_page_has_prev_false(self):
-        """第一页没有上一页."""
-        params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=100)
-        assert meta.has_prev is False
 
-    def test_first_page_has_next_true(self):
-        """第一页（数据多时有下一页."""
-        params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=100)
-        assert meta.has_next is True
+class TestPaginationMetaEdgeCases:
+    """PaginationMeta 补充边界场景."""
 
-    def test_last_page_has_next_false(self):
-        """最后一页没有下一页."""
-        params = PaginationParams(page=10, page_size=10)
-        meta = PaginationMeta.from_params(params, total=100)
-        assert meta.has_next is False
-
-    def test_last_page_has_prev_true(self):
-        """最后一页有上一页."""
-        params = PaginationParams(page=10, page_size=10)
-        meta = PaginationMeta.from_params(params, total=100)
-        assert meta.has_prev is True
-
-    def test_middle_page_has_both(self):
-        """中间页上下都有."""
-        params = PaginationParams(page=5, page_size=10)
-        meta = PaginationMeta.from_params(params, total=100)
-        assert meta.has_prev is True
-        assert meta.has_next is True
-
-    def test_total_pages_exact_division(self):
-        """整除时总页数正确."""
-        params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=100)
-        assert meta.total_pages == 10
-
-    def test_total_pages_with_remainder(self):
-        """有余数时向上取整."""
-        params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=105)
-        assert meta.total_pages == 11
-
-    def test_total_pages_single_item(self):
-        """1条数据总页数=1."""
-        params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=1)
-        assert meta.total_pages == 1
-
-    def test_total_zero_gives_zero_pages(self):
-        """0条数据总页数=0."""
-        params = PaginationParams(page=1, page_size=10)
+    def test_total_0_page_1(self):
+        """total=0, page=1 时 total_pages=0, 无上下页."""
+        params = PaginationParams(page=1, page_size=20)
         meta = PaginationMeta.from_params(params, total=0)
         assert meta.total_pages == 0
-
-    def test_total_zero_has_prev_false(self):
-        """0条数据has_prev=False."""
-        params = PaginationParams(page=1, page_size=10)
-        meta = PaginationMeta.from_params(params, total=0)
+        assert meta.has_next is False
         assert meta.has_prev is False
 
-    def test_total_zero_has_next_false(self):
-        """0条数据has_next=False."""
-        params = PaginationParams(page=1, page_size=10)
+    def test_total_0_page_beyond(self):
+        """total=0, page>1 时 has_prev=True（因为page>1）."""
+        params = PaginationParams(page=3, page_size=20)
         meta = PaginationMeta.from_params(params, total=0)
-        assert meta.has_next is False
-
-    def test_page_exactly_total_pages_no_next(self):
-        """当前页等于总页数时没有下一页."""
-        params = PaginationParams(page=5, page_size=10)
-        meta = PaginationMeta.from_params(params, total=50)
-        assert meta.has_next is False
-        assert meta.total_pages == 5
-
-    def test_page_beyond_total_pages(self):
-        """页码超过总页数时has_next=False."""
-        params = PaginationParams(page=20, page_size=10)
-        meta = PaginationMeta.from_params(params, total=50)
+        assert meta.total_pages == 0
         assert meta.has_next is False
         assert meta.has_prev is True
 
-    def test_preserves_page_and_page_size(self):
-        """保留输入的page和page_size."""
-        params = PaginationParams(page=3, page_size=25)
-        meta = PaginationMeta.from_params(params, total=200)
-        assert meta.page == 3
-        assert meta.page_size == 25
-        assert meta.total == 200
+    def test_exact_last_page(self):
+        """刚好是最后一页时 has_next=False."""
+        params = PaginationParams(page=5, page_size=10)
+        meta = PaginationMeta.from_params(params, total=50)
+        assert meta.total_pages == 5
+        assert meta.has_next is False
+        assert meta.has_prev is True
 
-    def test_page_size_1_total_1(self):
-        """每页1条，1条数据."""
+    def test_one_more_than_exact(self):
+        """比整数页多1条时总页数+1."""
+        params = PaginationParams(page=1, page_size=10)
+        meta = PaginationMeta.from_params(params, total=51)
+        assert meta.total_pages == 6
+
+    def test_page_exactly_total_pages(self):
+        """page == total_pages 时 has_next=False."""
+        params = PaginationParams(page=3, page_size=10)
+        meta = PaginationMeta.from_params(params, total=30)
+        assert meta.has_next is False
+
+    def test_total_1_page_1_size_1(self):
+        """1条数据1页."""
         params = PaginationParams(page=1, page_size=1)
         meta = PaginationMeta.from_params(params, total=1)
         assert meta.total_pages == 1
@@ -202,118 +329,60 @@ class TestPaginationMetaFromParams:
         assert meta.has_prev is False
 
 
-class TestPaginatedResponseCreate:
-    """PaginatedResponse.create 创建分页响应."""
-
-    def test_creates_with_data_and_meta(self):
-        """创建包含data和pagination."""
-        params = PaginationParams(page=1, page_size=10)
-        data = [{"id": i} for i in range(10)]
-        resp = PaginatedResponse.create(data, params, total=25)
-        assert resp.data == data
-        assert resp.pagination.page == 1
-        assert resp.pagination.total == 25
-        assert resp.pagination.total_pages == 3
-
-    def test_empty_data(self):
-        """空数据响应."""
-        params = PaginationParams(page=1, page_size=10)
-        resp = PaginatedResponse.create([], params, total=0)
-        assert resp.data == []
-        assert resp.pagination.total == 0
-        assert resp.pagination.total_pages == 0
+# ── paginate 补充边界 ──────────────────────────────────────────────────────
 
 
-class TestPaginateInMemory:
-    """paginate 内存分页函数."""
+class TestPaginateEdgeCases:
+    """paginate 补充边界场景."""
 
-    def test_first_page(self):
-        """第一页返回前N条."""
-        items = list(range(50))
-        params = PaginationParams(page=1, page_size=10)
-        result = paginate(items, params)
-        assert result.data == list(range(10))
-        assert result.pagination.total == 50
-        assert result.pagination.total_pages == 5
-        assert result.pagination.has_next is True
-        assert result.pagination.has_prev is False
+    def test_single_item_list(self):
+        """单元素列表."""
+        result = paginate([42], PaginationParams(page=1, page_size=10))
+        assert result.data == [42]
+        assert result.pagination.total == 1
+        assert result.pagination.total_pages == 1
 
-    def test_middle_page(self):
-        """中间页."""
-        items = list(range(50))
-        params = PaginationParams(page=3, page_size=10)
-        result = paginate(items, params)
-        assert result.data == list(range(20, 30))
-        assert result.pagination.has_prev is True
-        assert result.pagination.has_next is True
-
-    def test_last_page(self):
-        """最后一页."""
-        items = list(range(50))
-        params = PaginationParams(page=5, page_size=10)
-        result = paginate(items, params)
-        assert result.data == list(range(40, 50))
+    def test_page_exactly_last(self):
+        """刚好在最后一页."""
+        items = list(range(25))
+        result = paginate(items, PaginationParams(page=3, page_size=10))
+        assert result.data == list(range(20, 25))
         assert result.pagination.has_next is False
-        assert result.pagination.has_prev is True
 
-    def test_last_page_not_full(self):
-        """最后一页不足page_size."""
-        items = list(range(45))
-        params = PaginationParams(page=5, page_size=10)
-        result = paginate(items, params)
-        assert result.data == list(range(40, 45))
-        assert len(result.data) == 5
-        assert result.pagination.total == 45
-        assert result.pagination.total_pages == 5
+    def test_page_past_end_returns_empty(self):
+        """页码超过总数返回空."""
+        items = list(range(5))
+        result = paginate(items, PaginationParams(page=10, page_size=10))
+        assert result.data == []
+        assert result.pagination.total == 5
 
-    def test_empty_list(self):
-        """空列表分页."""
-        items = []
-        params = PaginationParams(page=1, page_size=10)
-        result = paginate(items, params)
+    def test_empty_list_page_1(self):
+        """空列表第1页."""
+        result = paginate([], PaginationParams(page=1, page_size=10))
         assert result.data == []
         assert result.pagination.total == 0
         assert result.pagination.total_pages == 0
 
-    def test_page_beyond_total(self):
-        """页码超过总页数返回空数据."""
-        items = list(range(5))
-        params = PaginationParams(page=10, page_size=10)
-        result = paginate(items, params)
-        assert result.data == []
-        assert result.pagination.total == 5
-        assert result.pagination.total_pages == 1
-        assert result.pagination.has_next is False
+    def test_page_size_1_iterates_all(self):
+        """page_size=1 时每页1条."""
+        items = ["a", "b", "c"]
+        r1 = paginate(items, PaginationParams(page=1, page_size=1))
+        r2 = paginate(items, PaginationParams(page=2, page_size=1))
+        r3 = paginate(items, PaginationParams(page=3, page_size=1))
+        assert r1.data == ["a"]
+        assert r2.data == ["b"]
+        assert r3.data == ["c"]
 
-    def test_single_item(self):
-        """单条数据分页."""
-        items = ["only"]
-        params = PaginationParams(page=1, page_size=10)
-        result = paginate(items, params)
-        assert result.data == ["only"]
-        assert result.pagination.total == 1
-        assert result.pagination.total_pages == 1
+    def test_does_not_mutate_input(self):
+        """不修改输入列表."""
+        items = [1, 2, 3, 4, 5]
+        original = items[:]
+        paginate(items, PaginationParams(page=1, page_size=2))
+        assert items == original
 
-    def test_page_size_larger_than_total(self):
-        """每页条数大于总数，第一页包含全部."""
+    def test_page_size_greater_than_total(self):
+        """每页条数大于总数."""
         items = list(range(5))
-        params = PaginationParams(page=1, page_size=100)
-        result = paginate(items, params)
+        result = paginate(items, PaginationParams(page=1, page_size=100))
         assert result.data == items
         assert result.pagination.total_pages == 1
-
-    def test_page_size_1(self):
-        """每页1条."""
-        items = ["a", "b", "c"]
-        params = PaginationParams(page=2, page_size=1)
-        result = paginate(items, params)
-        assert result.data == ["b"]
-        assert result.pagination.total_pages == 3
-
-    def test_preserves_original_list(self):
-        """不修改原始列表."""
-        items = [1, 2, 3, 4, 5]
-        original = items.copy()
-        params = PaginationParams(page=1, page_size=2)
-        paginate(items, params)
-        assert items == original
diff --git a/tests/unit/test_text_splitter.py b/tests/unit/test_text_splitter.py
index 13377df2e..c87a3ad72 100755
--- a/tests/unit/test_text_splitter.py
+++ b/tests/unit/test_text_splitter.py
@@ -1,178 +1,296 @@
-"""文本分段器纯逻辑测试 — split_text.
-
-覆盖空文本、短文本、句子边界分段、超长句强制切段、过短段合并等场景。
-"""
+"""文本分段工具单元测试."""
 
 from __future__ import annotations
 
 import pytest
 
-from application.tts_job.text_splitter import split_text
+from packages.application.tts_job.text_splitter import split_text
 
 
-class TestSplitTextEmptyOrShort:
-    """空文本与短文本."""
+class TestSplitText:
+    """split_text 函数测试"""
 
     def test_empty_string_returns_empty_list(self):
-        """空字符串返回空列表."""
+        """空字符串返回空列表"""
         assert split_text("") == []
 
     def test_whitespace_only_returns_empty_list(self):
-        """纯空白字符串返回空列表."""
-        assert split_text("   \n\t  ") == []
+        """纯空白字符返回空列表"""
+        assert split_text("   \n  \t  ") == []
 
-    def test_none_not_supported(self):
-        """None不支持（strip会报错）."""
-        with pytest.raises(AttributeError):
-            split_text(None)
-
-    def test_short_text_single_segment(self):
-        """短文本不分割，单段返回."""
-        text = "你好世界。"
+    def test_short_text_returns_single_segment(self):
+        """短文本直接返回单段"""
+        text = "这是一段短文本。"
         result = split_text(text, max_chars=500)
         assert result == [text]
 
-    def test_exactly_max_chars_single_segment(self):
-        """刚好等于max_chars时不分段."""
+    def test_text_length_equals_max_chars(self):
+        """文本长度恰好等于 max_chars 时返回单段"""
         text = "a" * 100
         result = split_text(text, max_chars=100)
         assert len(result) == 1
         assert len(result[0]) == 100
 
-    def test_under_max_chars_single_segment(self):
-        """少于max_chars时不分段."""
-        text = "a" * 50
+    def test_splits_on_sentence_boundary(self):
+        """在句子边界处分段"""
+        # 构造长文本，确保超过 max_chars
+        sentences = ["今天天气真好。我们一起去公园散步吧。", "公园里有很多花。还有很多小朋友在玩耍。"] * 10
+        text = "".join(sentences)
+
+        result = split_text(text, max_chars=200)
+
+        assert len(result) >= 2
+        # 每段都不超过 max_chars
+        for seg in result:
+            assert len(seg) <= 200
+
+    def test_all_segments_within_max_chars(self):
+        """所有分段都不超过 max_chars"""
+        text = "这是第一句话。这是第二句话。这是第三句话。这是第四句话。这是第五句话。" * 10
+
         result = split_text(text, max_chars=100)
-        assert len(result) == 1
-        assert len(result[0]) == 50
 
-
-class TestSplitTextSentenceBoundary:
-    """句子边界分段."""
-
-    def test_split_by_period(self):
-        """按句号分段."""
-        text = "第一句内容。" + "第二句内容。" * 50
-        result = split_text(text, max_chars=100)
-        assert len(result) > 1
-        # 每段都不超过max_chars
         for seg in result:
             assert len(seg) <= 100
-        # 合并后等于原文（去空格后近似）
-        assert "".join(result) == text.replace(" ", "")
 
-    def test_split_by_question_mark(self):
-        """按问号分段."""
-        text = "你好吗？" + "我很好。" * 50
-        result = split_text(text, max_chars=80)
+    def test_long_single_sentence_hard_cut(self):
+        """超长单句会被硬切"""
+        text = "a" * 1000  # 没有标点
+
+        result = split_text(text, max_chars=200)
+
         assert len(result) > 1
+        for seg in result:
+            assert len(seg) <= 200
+
+    def test_newline_is_sentence_end(self):
+        """换行符作为句子结束符"""
+        text = "第一行内容\n第二行内容\n第三行内容" * 10
+
+        result = split_text(text, max_chars=50)
+
+        assert len(result) > 1
+        for seg in result:
+            assert len(seg) <= 50
+
+    def test_chinese_punctuation(self):
+        """中文标点（。！？；）作为句子结束符"""
+        text = "你好！今天吃什么？我吃米饭；你呢？我也吃米饭。" * 10
+
+        result = split_text(text, max_chars=80)
+
         for seg in result:
             assert len(seg) <= 80
 
-    def test_split_by_exclamation_mark(self):
-        """按感叹号分段."""
-        text = "太棒了！" + "真的好。" * 50
+    def test_english_punctuation(self):
+        """英文标点（.!?;）作为句子结束符"""
+        text = "Hello! How are you? I'm fine; thank you. Good bye." * 10
+
         result = split_text(text, max_chars=80)
-        assert len(result) > 1
+
+        for seg in result:
+            assert len(seg) <= 80
+
+    def test_merged_short_segments(self):
+        """过短的段落会被合并"""
+        # 构造很多短句
+        text = "你好。再见。谢谢。抱歉。好的。不行。可以。去吧。" * 5  # 每句3-4字
 
-    def test_split_by_newline(self):
-        """按换行符分段."""
-        lines = ["这是第一行很长的内容" * 5 for _ in range(10)]
-        text = "\n".join(lines)
         result = split_text(text, max_chars=100)
-        assert len(result) > 1
+
+        # 合并后段数应该比单纯按句切的少
+        assert len(result) < len(text) // 3  # 粗略估计
         for seg in result:
             assert len(seg) <= 100
 
-    def test_split_by_semicolon_fullwidth(self):
-        """按全角分号分段."""
-        text = "第一项；" + "第二项内容。" * 40
-        result = split_text(text, max_chars=80)
-        assert len(result) > 1
+    def test_preserves_content(self):
+        """分段后内容总和与原文基本一致（忽略strip的空白）"""
+        text = "这是测试文本。包含多个句子。用来验证分段正确性。" * 5
 
-    def test_split_by_english_period(self):
-        """按英文句号也分段（_SENTENCE_ENDS包含.）."""
-        text = "Hello. " + "World. " * 50
-        result = split_text(text, max_chars=80)
-        assert len(result) > 1
+        result = split_text(text, max_chars=50)
 
-    def test_split_by_english_question(self):
-        """按英文问号分段."""
-        text = "Really? " + "Yes. " * 50
-        result = split_text(text, max_chars=80)
-        assert len(result) > 1
+        # 合并所有分段，去掉空白后应该与原文去掉空白后基本一致
+        combined = "".join(result).replace(" ", "")
+        original = text.strip().replace(" ", "")
+        assert combined == original
 
-    def test_split_by_english_exclamation(self):
-        """按英文感叹号分段."""
-        text = "Wow! " + "Great. " * 50
-        result = split_text(text, max_chars=80)
-        assert len(result) > 1
+    def test_custom_max_chars(self):
+        """支持自定义 max_chars"""
+        text = "测试" * 100  # 200字
 
-    def test_short_sentences_not_split(self):
-        """短句（<50字）即使有句号也不立刻切，等累积到一定长度."""
-        # 每句5字，即使有句号也不会在50字前切
-        text = "你好。" * 5  # 15字符
+        result_50 = split_text(text, max_chars=50)
+        result_100 = split_text(text, max_chars=100)
+
+        # max_chars 越小，段数应该越多
+        assert len(result_50) >= len(result_100)
+
+    def test_single_char_text(self):
+        """单字符文本"""
+        assert split_text("好", max_chars=10) == ["好"]
+
+    def test_text_with_only_punctuation(self):
+        """纯标点文本"""
+        text = "。。。。。。。。。。"  # 10个句号
+        result = split_text(text, max_chars=5)
+
+        assert len(result) >= 1
+        for seg in result:
+            assert len(seg) <= 5
+
+    def test_mixed_content(self):
+        """中英文混合内容"""
+        text = "今天的天气是 sunny and warm。我们去了 park 玩。真的很开心！" * 5
+
+        result = split_text(text, max_chars=80)
+
+        for seg in result:
+            assert len(seg) <= 80
+
+
+# ── 短文本与空文本补充 ──────────────────────────────────────────────────────
+
+
+class TestSplitTextEmptyAndShort:
+    """空文本与短文本补充场景."""
+
+    def test_whitespace_only_returns_empty(self):
+        """纯空白文本返回空列表."""
+        assert split_text("   \n\t  ") == []
+
+    def test_single_char(self):
+        """单字符文本."""
+        assert split_text("好", max_chars=10) == ["好"]
+
+    def test_exactly_max_chars_no_split(self):
+        """刚好等于 max_chars 不分割."""
+        text = "a" * 100
         result = split_text(text, max_chars=100)
-        # 因为每段至少50字才在句子边界切，所以15字的文本应该是1段
         assert len(result) == 1
+        assert result[0] == text
 
-
-class TestSplitTextLongSentenceForceSplit:
-    """超长单句强制切段."""
-
-    def test_single_very_long_sentence_forced_split(self):
-        """单句超长时强制切段."""
-        text = "啊" * 200  # 没有标点，200字
+    def test_one_over_max_chars_splits(self):
+        """超过 max_chars 1 个字符就会分割."""
+        text = "a" * 101
         result = split_text(text, max_chars=100)
         assert len(result) >= 2
-        for seg in result:
-            assert len(seg) <= 100
 
-    def test_force_split_preserves_all_chars(self):
-        """强制切段不丢字符."""
+    def test_none_raises(self):
+        """None 输入抛 AttributeError（strip 失败）."""
+        with pytest.raises(AttributeError):
+            split_text(None)
+
+
+# ── 句子边界分段补充 ──────────────────────────────────────────────────────
+
+
+class TestSplitTextSentenceBoundaries:
+    """句子边界分段补充场景."""
+
+    def test_split_on_fullwidth_period(self):
+        """全角句号分段."""
+        text = "第一句很长的内容。" * 20
+        result = split_text(text, max_chars=60)
+        assert len(result) > 1
+        for seg in result:
+            assert len(seg) <= 60
+
+    def test_split_on_fullwidth_question(self):
+        """全角问号分段."""
+        text = "你知道这是为什么吗？" + "是的。" * 20
+        result = split_text(text, max_chars=60)
+        assert len(result) > 1
+
+    def test_split_on_fullwidth_exclamation(self):
+        """全角感叹号分段."""
+        text = "真是太棒了！" + "内容。" * 20
+        result = split_text(text, max_chars=60)
+        assert len(result) > 1
+
+    def test_split_on_newline(self):
+        """换行符分段."""
+        lines = ["这是第一行很长的一段文字内容" * 3 for _ in range(5)]
+        text = "\n".join(lines)
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+
+    def test_split_on_semicolon(self):
+        """全角分号分段."""
+        text = "第一项内容；" + "其他内容。" * 20
+        result = split_text(text, max_chars=60)
+        assert len(result) > 1
+
+    def test_english_period_splits(self):
+        """英文句号分段."""
+        text = "Hello world. " * 30
+        result = split_text(text, max_chars=80)
+        assert len(result) > 1
+
+    def test_short_sentences_stay_merged(self):
+        """短句（都 < 50字的句子不会单独成段，会累积到一起."""
+        text = "你好。我好。大家好。"
+        result = split_text(text, max_chars=200)
+        assert len(result) == 1
+
+
+# ── 长句强制切段补充 ──────────────────────────────────────────────────────
+
+
+class TestSplitTextLongSentenceForce:
+    """超长单句强制切段补充."""
+
+    def test_no_punctuation_forced_split(self):
+        """完全没有标点的超长文本硬切."""
+        text = "字" * 300
+        result = split_text(text, max_chars=100)
+        assert len(result) == 3
+        for seg in result:
+            assert len(seg) == 100
+
+    def test_force_split_preserves_content(self):
+        """硬切不丢字符."""
         text = "a" * 250
         result = split_text(text, max_chars=100)
-        # 所有段的总长度应等于原文（去掉空白可能有细微差异，但纯字母应该不变）
         assert sum(len(s) for s in result) == 250
 
-    def test_mixed_long_and_short_sentences(self):
+    def test_mixed_long_and_short(self):
         """长句短句混合."""
-        long_part = "非常长的句子没有标点符号" * 20
-        text = long_part + "。结束句。"
+        long_part = "非常长的句子没有标点符号" * 15
+        text = long_part + "。结尾。"
         result = split_text(text, max_chars=100)
         assert len(result) > 1
         for seg in result:
             assert len(seg) <= 100
 
 
-class TestSplitTextShortSegmentMerging:
-    """过短段落合并."""
+# ── 短段合并补充 ─────────────────────────────────────────────────────────
 
-    def test_short_final_segment_merged(self):
-        """最后一段过短会被合并到前一段（如果不超限）."""
-        # 构造两段，第二段很短
-        text = "第一部分内容" * 10 + "。" + "短尾巴。"
-        result = split_text(text, max_chars=200)
-        # 短尾巴应该被合并，不会单独成为一段
-        assert len(result) <= 2  # 可能1段或2段，但不会有3段
 
-    def test_very_short_segments_combined(self):
-        """多个极短段会被合并."""
-        # 构造多个短句，都<50字
-        sentences = ["你好。", "我好。", "大家好。", "天气不错。", "一起玩吧。", "好的。"]
+class TestSplitTextShortSegmentMerge:
+    """短段合并补充场景."""
+
+    def test_multiple_short_sentences_merged(self):
+        """多个短句合并成一段."""
+        sentences = ["你好。", "我好。", "大家好。", "天气好。", "心情好。"]
         text = "".join(sentences)
         result = split_text(text, max_chars=200)
-        # 总长度很短，应该合并成1段
         assert len(result) == 1
 
+    def test_short_tail_merged(self):
+        """尾部短段被合并到前一段."""
+        # 前面一段接近 max_chars，尾部很短
+        long_part = "一二三四五六七八九十" * 9 + "。"  # ~90字
+        tail = "完。"  # 2字
+        text = long_part + tail
+        result = split_text(text, max_chars=100)
+        # 尾部短的应该被合并
+        assert len(result) <= 2
+
+
+# ── 边界情况补充 ─────────────────────────────────────────────────────────
+
 
 class TestSplitTextEdgeCases:
-    """边界情况."""
-
-    def test_single_character(self):
-        """单字符."""
-        result = split_text("好", max_chars=10)
-        assert result == ["好"]
+    """边界情况补充."""
 
     def test_only_punctuation(self):
         """纯标点符号."""
@@ -180,40 +298,30 @@ class TestSplitTextEdgeCases:
         result = split_text(text, max_chars=10)
         assert len(result) == 1
 
-    def test_custom_max_chars_small(self):
-        """很小的max_chars."""
-        text = "一二三四五六七八九十。" * 5
-        result = split_text(text, max_chars=20)
-        assert len(result) > 1
-        for seg in result:
-            assert len(seg) <= 20
-
     def test_mixed_chinese_english(self):
         """中英文混合."""
-        text = "今天天气很好。Today is a nice day. 我们出去玩吧！Let's go out and play." * 20
-        result = split_text(text, max_chars=150)
+        text = "你好Hello。World!" * 20
+        result = split_text(text, max_chars=100)
         assert len(result) > 1
         for seg in result:
-            assert len(seg) <= 150
+            assert len(seg) <= 100
 
-    def test_no_punctuation_long_text(self):
-        """完全没有标点的长文本，只能硬切."""
-        text = "字" * 500
-        result = split_text(text, max_chars=100)
-        assert len(result) == 5
-        for seg in result:
-            assert len(seg) == 100
-
-    def test_strip_leading_trailing_whitespace(self):
+    def test_strip_whitespace(self):
         """首尾空白被去除."""
         text = "   你好世界。   "
         result = split_text(text, max_chars=100)
         assert result == ["你好世界。"]
 
     def test_total_length_preserved(self):
-        """分段后总字符数大致等于原文（去除首尾空白后）."""
-        text = "这是一段测试文本。" * 30
+        """分段后总长度等于原文 strip 后长度."""
+        text = "这是一段用于测试的文本内容。" * 20
         result = split_text(text, max_chars=100)
-        joined = "".join(result)
-        # 因为strip的原因可能略有差异，但应该接近
-        assert len(joined) == len(text.strip())
+        assert "".join(result) == text.strip()
+
+    def test_custom_small_max_chars(self):
+        """很小的 max_chars."""
+        text = "一二三四五六七八九十。" * 5
+        result = split_text(text, max_chars=20)
+        assert len(result) > 1
+        for seg in result:
+            assert len(seg) <= 20
diff --git a/tests/unit/test_url_security.py b/tests/unit/test_url_security.py
index abe7e7c85..04b48482d 100755
--- a/tests/unit/test_url_security.py
+++ b/tests/unit/test_url_security.py
@@ -1,532 +1,815 @@
-"""URL安全校验纯逻辑测试 — SSRF防护/魔数校验/可信域名.
-
-聚焦纯函数校验逻辑，DNS解析和实际下载用mock隔离。
 """
+url_security URL安全校验单元测试
 
-from __future__ import annotations
+覆盖：
+- validate_url_safety: scheme/主机/端口/SSRF/内网域名/白名单
+- is_url_safe: 便捷函数
+- UrlSecurityError / NoRedirectHandler
+- _validate_magic_number: 文件魔数校验
+- safe_download_file / safe_download_bytes: mock 网络测试
+"""
 
 import ipaddress
 import os
 import tempfile
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 
-from shared.url_security import (
+from packages.shared.url_security import (
+    ALLOWED_AUDIO_MIME_TYPES,
+    ALLOWED_IMAGE_MIME_TYPES,
     ALLOWED_PORTS,
     ALLOWED_SCHEMES,
+    MAX_URL_LENGTH,
+    NoRedirectHandler,
     UrlSecurityError,
     _check_internal_hostnames,
     _check_ssrf_ip,
     _is_trusted_domain,
     _validate_magic_number,
     is_url_safe,
+    safe_download_bytes,
+    safe_download_file,
     validate_url_safety,
 )
 
+# ── validate_url_safety 基础校验 ─────────────────────────────────────────────
+
+
+class TestValidateUrlSafetyBasics:
+    """URL 安全校验基础测试"""
+
+    def test_valid_http_url(self):
+        url = "http://example.com/file.mp4"
+        result = validate_url_safety(url)
+        assert result == url
+
+    def test_valid_https_url(self):
+        url = "https://example.com/file.mp4"
+        result = validate_url_safety(url)
+        assert result == url
+
+    def test_empty_url_raises(self):
+        with pytest.raises(UrlSecurityError, match="为空"):
+            validate_url_safety("")
+
+    def test_none_url_raises(self):
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety(None)
+
+    def test_url_too_long_raises(self):
+        long_url = "https://example.com/" + "a" * 2050
+        with pytest.raises(UrlSecurityError, match="过长"):
+            validate_url_safety(long_url)
+
+    def test_url_at_max_length_ok(self):
+        base = "https://example.com/"
+        pad = "a" * (MAX_URL_LENGTH - len(base))
+        url = base + pad
+        assert len(url) <= MAX_URL_LENGTH
+        result = validate_url_safety(url)
+        assert result == url
+
+    def test_invalid_scheme_ftp_raises(self):
+        with pytest.raises(UrlSecurityError, match="scheme"):
+            validate_url_safety("ftp://example.com/file")
+
+    def test_invalid_scheme_file_raises(self):
+        with pytest.raises(UrlSecurityError, match="scheme"):
+            validate_url_safety("file:///etc/passwd")
+
+    def test_invalid_scheme_data_raises(self):
+        with pytest.raises(UrlSecurityError, match="scheme"):
+            validate_url_safety("data:text/html,<script>")
+
+    def test_missing_scheme_raises(self):
+        with pytest.raises(UrlSecurityError, match="scheme"):
+            validate_url_safety("example.com/file")
+
+    def test_missing_hostname_raises(self):
+        with pytest.raises(UrlSecurityError, match="主机名"):
+            validate_url_safety("http:///path")
+
+    def test_uppercase_scheme_normalized(self):
+        """HTTP/HTTPS 大写也能通过"""
+        url = "HTTPS://example.com/file"
+        # scheme 检查用 lower 比较
+        result = validate_url_safety(url)
+        assert result == url
+
+    def test_default_port_80_ok(self):
+        url = "http://example.com:80/file"
+        result = validate_url_safety(url)
+        assert result == url
+
+    def test_default_port_443_ok(self):
+        url = "https://example.com:443/file"
+        result = validate_url_safety(url)
+        assert result == url
+
+    def test_non_standard_port_raises(self):
+        with pytest.raises(UrlSecurityError, match="端口"):
+            validate_url_safety("http://example.com:8080/file")
+
+    def test_port_22_ssh_raises(self):
+        with pytest.raises(UrlSecurityError, match="端口"):
+            validate_url_safety("http://example.com:22/file")
+
+    def test_port_3306_mysql_raises(self):
+        with pytest.raises(UrlSecurityError, match="端口"):
+            validate_url_safety("http://example.com:3306/file")
+
+
+# ── 内网主机名 / SSRF 防护 ───────────────────────────────────────────────────
+
+
+class TestInternalHostnameProtection:
+    """内网主机名防护测试"""
+
+    def test_localhost_raises(self):
+        with pytest.raises(UrlSecurityError, match="内部主机名"):
+            validate_url_safety("http://localhost/file")
+
+    def test_localhost_mixed_case_raises(self):
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety("http://LocalHost/file")
+
+    def test_localhost_localdomain_raises(self):
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("localhost.localdomain")
+
+    def test_metadata_hostname_raises(self):
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("metadata")
+
+    def test_metadata_google_internal_raises(self):
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("metadata.google.internal")
+
+    def test_dot_local_domain_raises(self):
+        with pytest.raises(UrlSecurityError, match="内网域名"):
+            validate_url_safety("http://myservice.local/file")
+
+    def test_dot_internal_domain_raises(self):
+        with pytest.raises(UrlSecurityError, match="内网域名"):
+            validate_url_safety("http://myservice.internal/file")
+
+    def test_dot_localdomain_raises(self):
+        with pytest.raises(UrlSecurityError):
+            _check_internal_hostnames("server.localdomain")
+
+    def test_loopback_ip_127_0_0_1_raises(self):
+        with pytest.raises(UrlSecurityError, match="直接 IP|回环"):
+            validate_url_safety("http://127.0.0.1/file")
+
+    def test_metadata_ip_169_254_raises(self):
+        """云元数据服务 IP"""
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety("http://169.254.169.254/latest/meta-data/")
+
+    def test_private_ip_10_raises(self):
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety("http://10.0.0.1/file")
+
+    def test_private_ip_172_16_raises(self):
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety("http://172.16.0.1/file")
+
+    def test_private_ip_192_168_raises(self):
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety("http://192.168.1.1/file")
+
+    def test_unspecified_ip_0_0_0_0_raises(self):
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety("http://0.0.0.0/file")
+
+    def test_ipv6_loopback_raises(self):
+        with pytest.raises(UrlSecurityError):
+            validate_url_safety("http://[::1]/file")
+
+    def test_public_ip_ok(self):
+        """公网IP在ALLOW_DIRECT_IP默认关闭时应被拦截"""
+        # 默认 ALLOW_DIRECT_IP = false
+        with pytest.raises(UrlSecurityError, match="直接 IP"):
+            validate_url_safety("http://8.8.8.8/file")
+
+
+# ── 可信域名白名单 ───────────────────────────────────────────────────────────
+
+
+class TestTrustedDomains:
+    """可信域名白名单测试"""
+
+    def test_is_trusted_domain_exact_match(self):
+        with patch("packages.shared.url_security.TRUSTED_DOMAINS", {"example.com", "cdn.example.org"}):
+            # 重新加载模块以应用环境变量不太现实，直接测函数
+            # 直接改全局状态再还原
+            import packages.shared.url_security as mod
+            from packages.shared.url_security import _is_trusted_domain
+
+            original = mod.TRUSTED_DOMAINS
+            mod.TRUSTED_DOMAINS = {"example.com", "cdn.example.org"}
+            try:
+                assert _is_trusted_domain("example.com") is True
+                assert _is_trusted_domain("cdn.example.org") is True
+            finally:
+                mod.TRUSTED_DOMAINS = original
+
+    def test_is_trusted_domain_subdomain(self):
+        import packages.shared.url_security as mod
+
+        original = mod.TRUSTED_DOMAINS
+        mod.TRUSTED_DOMAINS = {"example.com"}
+        try:
+            assert mod._is_trusted_domain("sub.example.com") is True
+            assert mod._is_trusted_domain("a.b.example.com") is True
+        finally:
+            mod.TRUSTED_DOMAINS = original
+
+    def test_is_trusted_domain_no_match(self):
+        import packages.shared.url_security as mod
+
+        original = mod.TRUSTED_DOMAINS
+        mod.TRUSTED_DOMAINS = {"example.com"}
+        try:
+            assert mod._is_trusted_domain("other.com") is False
+            assert mod._is_trusted_domain("notexample.com") is False
+        finally:
+            mod.TRUSTED_DOMAINS = original
+
+    def test_validate_with_trusted_domains_restricted(self):
+        """白名单非空时，不在白名单中的域名被拒"""
+        import packages.shared.url_security as mod
+
+        original = mod.TRUSTED_DOMAINS
+        mod.TRUSTED_DOMAINS = {"trusted.com"}
+        try:
+            # 不在白名单中 - 在 _is_trusted_domain 检查时就被拒，不走 DNS
+            with pytest.raises(UrlSecurityError, match="白名单"):
+                validate_url_safety("https://untrusted.com/file")
+
+            # 在白名单中 - 需要 mock DNS 解析避免实际网络请求
+            with patch("packages.shared.url_security._check_ssrf_domain"):
+                result = validate_url_safety("https://trusted.com/file")
+                assert result == "https://trusted.com/file"
+                # 子域名
+                result = validate_url_safety("https://sub.trusted.com/file")
+                assert result == "https://sub.trusted.com/file"
+        finally:
+            mod.TRUSTED_DOMAINS = original
+
+
+# ── is_url_safe 便捷函数 ─────────────────────────────────────────────────────
+
+
+class TestIsUrlSafe:
+    """is_url_safe 便捷函数测试"""
+
+    def test_safe_url_returns_true(self):
+        assert is_url_safe("https://example.com/file") is True
+
+    def test_unsafe_url_returns_false(self):
+        assert is_url_safe("http://localhost/file") is False
+
+    def test_empty_url_returns_false(self):
+        assert is_url_safe("") is False
+
+    def test_invalid_scheme_returns_false(self):
+        assert is_url_safe("ftp://example.com/file") is False
+
+
+# ── UrlSecurityError 异常类 ───────────────────────────────────────────────────
+
 
 class TestUrlSecurityError:
-    """UrlSecurityError 异常类."""
+    """UrlSecurityError 异常类测试"""
 
-    def test_is_value_error(self):
-        """继承自 ValueError."""
+    def test_is_value_error_subclass(self):
         assert issubclass(UrlSecurityError, ValueError)
 
-    def test_message_preserved(self):
-        """错误消息被保留."""
+    def test_error_message(self):
         err = UrlSecurityError("test message")
         assert str(err) == "test message"
 
 
-class TestValidateUrlSafetyBasic:
-    """validate_url_safety 基础校验（不涉及DNS解析）."""
+# ── NoRedirectHandler ────────────────────────────────────────────────────────
 
-    def test_empty_url_rejected(self):
-        """空URL被拒绝."""
-        with pytest.raises(UrlSecurityError, match="URL 为空"):
-            validate_url_safety("")
 
-    def test_none_url_rejected(self):
-        """None URL被拒绝."""
+class TestNoRedirectHandler:
+    """NoRedirectHandler 测试"""
+
+    def test_redirect_request_returns_none(self):
+        handler = NoRedirectHandler()
+        result = handler.redirect_request(
+            MagicMock(),
+            MagicMock(),
+            302,
+            "Found",
+            {"Location": "http://other.com"},
+            "http://other.com",
+        )
+        assert result is None
+
+
+# ── 魔数校验 ─────────────────────────────────────────────────────────────────
+
+
+class TestMagicNumberValidation:
+    """文件魔数校验测试"""
+
+    def test_valid_png(self, tmp_path):
+        f = tmp_path / "test.png"
+        # PNG 文件头: 89 50 4E 47 0D 0A 1A 0A
+        f.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
+        # 不抛异常 = 通过
+        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_valid_jpeg(self, tmp_path):
+        f = tmp_path / "test.jpg"
+        # JPEG 文件头: FF D8 FF
+        f.write_bytes(b"\xff\xd8\xff\xe0" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_valid_gif87a(self, tmp_path):
+        f = tmp_path / "test.gif"
+        f.write_bytes(b"GIF87a" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_valid_gif89a(self, tmp_path):
+        f = tmp_path / "test.gif"
+        f.write_bytes(b"GIF89a" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_valid_webp(self, tmp_path):
+        f = tmp_path / "test.webp"
+        # RIFF....WEBP
+        data = bytearray(b"RIFF")
+        data += b"\x00\x00\x00\x00"  # size placeholder
+        data += b"WEBP"
+        data += b"\x00" * 100
+        f.write_bytes(bytes(data))
+        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_valid_bmp(self, tmp_path):
+        f = tmp_path / "test.bmp"
+        f.write_bytes(b"BM" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_valid_wav(self, tmp_path):
+        f = tmp_path / "test.wav"
+        # RIFF....WAVE
+        data = bytearray(b"RIFF")
+        data += b"\x00\x00\x00\x00"
+        data += b"WAVE"
+        data += b"\x00" * 100
+        f.write_bytes(bytes(data))
+        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+
+    def test_valid_mp3_id3(self, tmp_path):
+        f = tmp_path / "test.mp3"
+        f.write_bytes(b"ID3\x03\x00\x00\x00\x00\x00\x00" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+
+    def test_valid_mp3_adts(self, tmp_path):
+        f = tmp_path / "test.mp3"
+        f.write_bytes(b"\xff\xfb\x90\x00" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+
+    def test_valid_ogg(self, tmp_path):
+        f = tmp_path / "test.ogg"
+        f.write_bytes(b"OggS\x00\x02\x00\x00" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+
+    def test_valid_flac(self, tmp_path):
+        f = tmp_path / "test.flac"
+        f.write_bytes(b"fLaC" + b"\x00" * 100)
+        _validate_magic_number(str(f), ALLOWED_AUDIO_MIME_TYPES)
+
+    def test_invalid_file_content_raises(self, tmp_path):
+        f = tmp_path / "test.bin"
+        f.write_bytes(b"this is not an image file at all")
+        with pytest.raises(UrlSecurityError, match="魔数"):
+            _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_empty_file_raises(self, tmp_path):
+        f = tmp_path / "empty.bin"
+        f.write_bytes(b"")
+        with pytest.raises(UrlSecurityError, match="为空"):
+            _validate_magic_number(str(f), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_nonexistent_file_raises(self, tmp_path):
+        with pytest.raises(UrlSecurityError, match="读取文件头失败"):
+            _validate_magic_number(str(tmp_path / "no_such_file"), ALLOWED_IMAGE_MIME_TYPES)
+
+    def test_no_allowed_mime_types_skips(self, tmp_path):
+        """allowed_mime_types 为空时跳过校验"""
+        f = tmp_path / "test.bin"
+        f.write_bytes(b"random data here")
+        # 不抛异常
+        _validate_magic_number(str(f), set())
+
+    def test_unknown_mime_types_skips(self, tmp_path):
+        """没有已知魔数的 MIME 类型跳过校验"""
+        f = tmp_path / "test.bin"
+        f.write_bytes(b"random data")
+        _validate_magic_number(str(f), {"application/x-unknown-type"})
+
+
+# ── safe_download_file (mock 网络) ───────────────────────────────────────────
+
+
+class TestSafeDownloadFile:
+    """safe_download_file 下载测试（mock 网络）"""
+
+    def test_download_success(self, tmp_path):
+        test_content = b"Hello, this is test file content!"
+        dest = str(tmp_path / "output.bin")
+
+        mock_resp = MagicMock()
+        mock_resp.headers = {"Content-Type": "application/octet-stream"}
+        mock_resp.read.side_effect = [test_content, b""]
+
+        with patch("packages.shared.url_security.NoRedirectHandler") as mock_handler_cls:
+            mock_handler = MagicMock()
+            mock_handler_cls.return_value = mock_handler
+
+            mock_opener = MagicMock()
+            mock_opener.open.return_value = mock_resp
+
+            with patch("urllib.request.build_opener", return_value=mock_opener):
+                size = safe_download_file(
+                    "https://example.com/test.bin",
+                    dest,
+                    purpose="test",
+                )
+
+        assert size == len(test_content)
+        with open(dest, "rb") as f:
+            assert f.read() == test_content
+
+    def test_download_with_mime_check_passes(self, tmp_path):
+        # PNG 文件
+        test_content = b"\x89PNG\r\n\x1a\n" + b"\x00" * 200
+        dest = str(tmp_path / "test.png")
+
+        mock_resp = MagicMock()
+        mock_resp.headers = {"Content-Type": "image/png"}
+        mock_resp.read.side_effect = [test_content, b""]
+
+        with patch("urllib.request.build_opener") as mock_build:
+            mock_opener = MagicMock()
+            mock_opener.open.return_value = mock_resp
+            mock_build.return_value = mock_opener
+
+            size = safe_download_file(
+                "https://example.com/test.png",
+                dest,
+                purpose="test",
+                allowed_mime_types={"image/png", "image/jpeg"},
+            )
+
+        assert size == len(test_content)
+
+    def test_download_mime_type_rejected(self, tmp_path):
+        test_content = b"GIF89a" + b"\x00" * 50
+        dest = str(tmp_path / "test.gif")
+
+        mock_resp = MagicMock()
+        mock_resp.headers = {"Content-Type": "image/gif"}
+        mock_resp.read.side_effect = [test_content, b""]
+
+        with patch("urllib.request.build_opener") as mock_build:
+            mock_opener = MagicMock()
+            mock_opener.open.return_value = mock_resp
+            mock_build.return_value = mock_opener
+
+            with pytest.raises(UrlSecurityError, match="Content-Type"):
+                safe_download_file(
+                    "https://example.com/test.gif",
+                    dest,
+                    purpose="test",
+                    allowed_mime_types={"image/png"},
+                )
+
+    def test_download_size_limit_exceeded(self, tmp_path):
+        """流式下载时超过大小限制被中断（无 Content-Length header）"""
+        dest = str(tmp_path / "big.bin")
+        chunk = b"x" * 1024  # 1KB chunks
+
+        mock_resp = MagicMock()
+        # 没有 Content-Length header，走流式检查
+        mock_resp.headers = {"Content-Type": "application/octet-stream"}
+        # 模拟多次读取，超过 5KB 限制（6个chunk = 6KB）
+        mock_resp.read.side_effect = [chunk] * 6 + [b""]
+
+        with patch("urllib.request.build_opener") as mock_build:
+            mock_opener = MagicMock()
+            mock_opener.open.return_value = mock_resp
+            mock_build.return_value = mock_opener
+
+            with pytest.raises(UrlSecurityError, match="超过大小限制"):
+                safe_download_file(
+                    "https://example.com/big.bin",
+                    dest,
+                    purpose="test",
+                    max_size=5000,  # 5KB limit
+                )
+
+    def test_download_content_length_too_large(self, tmp_path):
+        dest = str(tmp_path / "big.bin")
+
+        mock_resp = MagicMock()
+        mock_resp.headers = {"Content-Type": "application/octet-stream", "Content-Length": "1000000"}
+        mock_resp.read.side_effect = [b"data"]
+
+        with patch("urllib.request.build_opener") as mock_build:
+            mock_opener = MagicMock()
+            mock_opener.open.return_value = mock_resp
+            mock_build.return_value = mock_opener
+
+            with pytest.raises(UrlSecurityError, match="文件过大"):
+                safe_download_file(
+                    "https://example.com/big.bin",
+                    dest,
+                    purpose="test",
+                    max_size=500000,
+                )
+
+    def test_download_localhost_rejected(self, tmp_path):
+        """内网 URL 在下载前就被拒"""
+        dest = str(tmp_path / "out.bin")
         with pytest.raises(UrlSecurityError):
-            validate_url_safety(None)
+            safe_download_file("http://localhost/file", dest)
 
-    def test_url_too_long_rejected(self):
-        """超长URL被拒绝."""
-        long_url = "https://example.com/" + "a" * 2048
-        with pytest.raises(UrlSecurityError, match="URL 过长"):
-            validate_url_safety(long_url)
-
-    def test_invalid_scheme_rejected(self):
-        """非法scheme被拒绝."""
-        with pytest.raises(UrlSecurityError, match="不允许的 URL scheme"):
-            validate_url_safety("ftp://example.com/file.mp3")
-
-    def test_file_scheme_rejected(self):
-        """file:// scheme被拒绝."""
-        with pytest.raises(UrlSecurityError, match="不允许的 URL scheme"):
-            validate_url_safety("file:///etc/passwd")
-
-    def test_no_scheme_rejected(self):
-        """无scheme被拒绝."""
-        with pytest.raises(UrlSecurityError, match="不允许的 URL scheme"):
-            validate_url_safety("example.com/file.mp3")
-
-    def test_http_scheme_allowed(self):
-        """http scheme允许（需要mock DNS）."""
-        with patch("shared.url_security._check_ssrf_domain") as mock_check:
-            result = validate_url_safety("http://example.com/audio.mp3")
-            assert result == "http://example.com/audio.mp3"
-            mock_check.assert_called_once()
-
-    def test_https_scheme_allowed(self):
-        """https scheme允许."""
-        with patch("shared.url_security._check_ssrf_domain") as mock_check:
-            result = validate_url_safety("https://example.com/audio.mp3")
-            assert result == "https://example.com/audio.mp3"
-            mock_check.assert_called_once()
-
-    def test_scheme_case_insensitive(self):
-        """scheme大小写不敏感."""
-        with patch("shared.url_security._check_ssrf_domain") as mock_check:
-            result = validate_url_safety("HTTPS://example.com/audio.mp3")
-            assert result == "HTTPS://example.com/audio.mp3"
-
-    def test_missing_hostname_rejected(self):
-        """缺少主机名被拒绝."""
-        with pytest.raises(UrlSecurityError, match="URL 缺少主机名"):
-            validate_url_safety("https:///path/to/file")
-
-    def test_non_standard_port_rejected(self):
-        """非标准端口被拒绝."""
-        with pytest.raises(UrlSecurityError, match="不允许的端口"):
-            validate_url_safety("https://example.com:8080/audio.mp3")
-
-    def test_port_22_rejected(self):
-        """SSH端口被拒绝."""
-        with pytest.raises(UrlSecurityError, match="不允许的端口"):
-            validate_url_safety("https://example.com:22/")
-
-    def test_port_80_allowed(self):
-        """80端口允许."""
-        with patch("shared.url_security._check_ssrf_domain") as mock_check:
-            result = validate_url_safety("http://example.com:80/audio.mp3")
-            assert result == "http://example.com:80/audio.mp3"
-
-    def test_port_443_allowed(self):
-        """443端口允许."""
-        with patch("shared.url_security._check_ssrf_domain") as mock_check:
-            result = validate_url_safety("https://example.com:443/audio.mp3")
-            assert result == "https://example.com:443/audio.mp3"
-
-    def test_default_http_port_implicit_80(self):
-        """http默认端口隐含80，不触发端口校验."""
-        with patch("shared.url_security._check_ssrf_domain") as mock_check:
-            result = validate_url_safety("http://example.com/audio.mp3")
-            assert "example.com" in result
-
-    def test_default_https_port_implicit_443(self):
-        """https默认端口隐含443，不触发端口校验."""
-        with patch("shared.url_security._check_ssrf_domain") as mock_check:
-            result = validate_url_safety("https://example.com/audio.mp3")
-            assert "example.com" in result
-
-    def test_purpose_parameter_logged(self):
-        """purpose参数不影响校验结果."""
-        with patch("shared.url_security._check_ssrf_domain"):
-            result = validate_url_safety("https://example.com/a.mp3", purpose="tts_download")
-            assert result == "https://example.com/a.mp3"
-
-    def test_url_with_path_and_query(self):
-        """带路径和query参数的URL正常通过."""
-        with patch("shared.url_security._check_ssrf_domain"):
-            url = "https://example.com/path/to/file.mp3?token=abc&expires=123"
-            result = validate_url_safety(url)
-            assert result == url
+    def test_download_invalid_scheme_rejected(self, tmp_path):
+        dest = str(tmp_path / "out.bin")
+        with pytest.raises(UrlSecurityError, match="scheme"):
+            safe_download_file("ftp://example.com/file", dest)
 
 
-class TestInternalHostnames:
-    """_check_internal_hostnames 内部主机名拦截."""
+# ── safe_download_bytes ───────────────────────────────────────────────────────
 
-    def test_localhost_blocked(self):
-        """localhost被拦截."""
-        with pytest.raises(UrlSecurityError, match="禁止访问内部主机名"):
-            _check_internal_hostnames("localhost")
 
-    def test_localhost_case_insensitive(self):
-        """大小写不敏感."""
+class TestSafeDownloadBytes:
+    """safe_download_bytes 测试"""
+
+    def test_download_returns_bytes(self, tmp_path):
+        test_content = b"hello bytes download test"
+
+        mock_resp = MagicMock()
+        mock_resp.headers = {"Content-Type": "application/octet-stream"}
+        mock_resp.read.side_effect = [test_content, b""]
+
+        with patch("urllib.request.build_opener") as mock_build:
+            mock_opener = MagicMock()
+            mock_opener.open.return_value = mock_resp
+            mock_build.return_value = mock_opener
+
+            result = safe_download_bytes(
+                "https://example.com/test.bin",
+                purpose="test",
+            )
+
+        assert result == test_content
+        assert isinstance(result, bytes)
+
+    def test_download_unsafe_url_raises(self):
         with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("LOCALHOST")
+            safe_download_bytes("http://127.0.0.1/secret")
 
-    def test_localhost_localdomain_blocked(self):
-        """localhost.localdomain被拦截."""
-        with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("localhost.localdomain")
 
-    def test_metadata_blocked(self):
-        """metadata被拦截."""
-        with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("metadata")
+# ── 常量导出验证 ─────────────────────────────────────────────────────────────
 
-    def test_metadata_google_internal_blocked(self):
-        """GCP元数据服务被拦截."""
-        with pytest.raises(UrlSecurityError):
-            _check_internal_hostnames("metadata.google.internal")
 
-    def test_local_domain_suffix_blocked(self):
-        """.local后缀被拦截."""
-        with pytest.raises(UrlSecurityError, match="禁止访问内网域名"):
-            _check_internal_hostnames("printer.local")
+class TestConstants:
+    """模块常量验证"""
 
-    def test_internal_domain_suffix_blocked(self):
-        """.internal后缀被拦截."""
-        with pytest.raises(UrlSecurityError, match="禁止访问内网域名"):
-            _check_internal_hostnames("service.internal")
+    def test_allowed_schemes(self):
+        assert "http" in ALLOWED_SCHEMES
+        assert "https" in ALLOWED_SCHEMES
+        assert len(ALLOWED_SCHEMES) == 2
 
-    def test_localdomain_suffix_blocked(self):
-        """.localdomain后缀被拦截."""
-        with pytest.raises(UrlSecurityError, match="禁止访问内网域名"):
-            _check_internal_hostnames("host.localdomain")
+    def test_allowed_ports(self):
+        assert 80 in ALLOWED_PORTS
+        assert 443 in ALLOWED_PORTS
+        assert len(ALLOWED_PORTS) == 2
 
-    def test_public_domain_passes(self):
-        """公网域名通过."""
-        _check_internal_hostnames("example.com")  # 不抛异常即通过
+    def test_max_url_length(self):
+        assert MAX_URL_LENGTH == 2048
 
-    def test_subdomain_of_public_domain_passes(self):
-        """公网域名子域名通过."""
-        _check_internal_hostnames("cdn.example.com")  # 不抛异常即通过
+# ── SSRF IP 检查详细覆盖 ──────────────────────────────────────────────────────
 
 
 class TestSSRFIPCheck:
-    """_check_ssrf_ip SSRF IP检查."""
+    """_check_ssrf_ip 各类型 IP 拦截覆盖."""
 
     def test_loopback_ipv4_blocked(self):
-        """IPv4回环地址被拦截."""
-        with pytest.raises(UrlSecurityError, match="回环地址"):
+        """IPv4 回环 127.0.0.1 被拦."""
+        with pytest.raises(UrlSecurityError):
             _check_ssrf_ip(ipaddress.ip_address("127.0.0.1"))
 
+    def test_loopback_ipv4_another_blocked(self):
+        """127.x 其他段也被拦."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("127.255.255.1"))
+
     def test_loopback_ipv6_blocked(self):
-        """IPv6回环地址被拦截."""
-        with pytest.raises(UrlSecurityError, match="回环地址"):
+        """IPv6 回环 ::1 被拦."""
+        with pytest.raises(UrlSecurityError):
             _check_ssrf_ip(ipaddress.ip_address("::1"))
 
-    def test_private_ip_10_blocked(self):
-        """10.x.x.x私有地址被拦截."""
-        with pytest.raises(UrlSecurityError, match="内网地址"):
-            _check_ssrf_ip(ipaddress.ip_address("10.0.0.1"))
-
-    def test_private_ip_172_blocked(self):
-        """172.16.x.x私有地址被拦截."""
-        with pytest.raises(UrlSecurityError, match="内网地址"):
-            _check_ssrf_ip(ipaddress.ip_address("172.16.0.1"))
-
-    def test_private_ip_192_blocked(self):
-        """192.168.x.x私有地址被拦截."""
-        with pytest.raises(UrlSecurityError, match="内网地址"):
-            _check_ssrf_ip(ipaddress.ip_address("192.168.1.1"))
-
-    def test_link_local_blocked(self):
-        """链路本地地址被拦截（is_private 先命中也可以，只要被拦就行）."""
+    def test_private_10_range_blocked(self):
+        """10.0.0.0/8 私有段被拦."""
         with pytest.raises(UrlSecurityError):
-            _check_ssrf_ip(ipaddress.ip_address("169.254.169.254"))
+            _check_ssrf_ip(ipaddress.ip_address("10.255.255.255"))
 
-    def test_multicast_blocked(self):
-        """组播地址被拦截."""
-        with pytest.raises(UrlSecurityError, match="组播地址"):
-            _check_ssrf_ip(ipaddress.ip_address("224.0.0.1"))
+    def test_private_172_range_blocked(self):
+        """172.16.0.0/12 私有段被拦."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("172.31.255.255"))
+
+    def test_private_192_range_blocked(self):
+        """192.168.0.0/16 私有段被拦."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("192.168.255.255"))
+
+    def test_link_local_ipv4_blocked(self):
+        """169.254.x.x 链路本地被拦."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("169.254.1.1"))
+
+    def test_multicast_ipv4_blocked(self):
+        """224.x 组播被拦."""
+        with pytest.raises(UrlSecurityError):
+            _check_ssrf_ip(ipaddress.ip_address("224.0.0.251"))
 
     def test_unspecified_ipv4_blocked(self):
-        """0.0.0.0被拦截."""
+        """0.0.0.0 未指定地址被拦."""
         with pytest.raises(UrlSecurityError):
             _check_ssrf_ip(ipaddress.ip_address("0.0.0.0"))
 
     def test_unspecified_ipv6_blocked(self):
-        """::被拦截."""
+        """:: 未指定地址被拦."""
         with pytest.raises(UrlSecurityError):
             _check_ssrf_ip(ipaddress.ip_address("::"))
 
-    def test_reserved_ip_blocked(self):
-        """保留地址被拦截（240.0.0.0/4 属于保留段）."""
+    def test_reserved_ipv4_blocked(self):
+        """240.0.0.0/4 保留段被拦（含在 is_private 或 is_reserved 中）."""
         with pytest.raises(UrlSecurityError):
             _check_ssrf_ip(ipaddress.ip_address("240.0.0.1"))
 
-    def test_public_ip_passes(self):
-        """公网IP通过（当ALLOW_DIRECT_IP=true时）."""
-        # 注意：公网IP在_check_ssrf_ip层面不拦截，拦截在validate_url_safety的ALLOW_DIRECT_IP层
-        _check_ssrf_ip(ipaddress.ip_address("8.8.8.8"))  # 不抛异常即通过
+    def test_public_ipv4_passes(self):
+        """公网 IPv4 通过 _check_ssrf_ip."""
+        _check_ssrf_ip(ipaddress.ip_address("8.8.8.8"))
 
-    def test_public_ip_another_passes(self):
-        """另一个公网IP通过."""
-        _check_ssrf_ip(ipaddress.ip_address("1.1.1.1"))  # 不抛异常即通过
+    def test_public_ipv4_another_passes(self):
+        """另一个公网 IPv4 通过."""
+        _check_ssrf_ip(ipaddress.ip_address("1.1.1.1"))
 
-    def test_ipv6_public_passes(self):
-        """IPv6公网地址通过."""
-        _check_ssrf_ip(ipaddress.ip_address("2001:4860:4860::8888"))  # 不抛异常即通过
+    def test_public_ipv6_passes(self):
+        """公网 IPv6 通过."""
+        _check_ssrf_ip(ipaddress.ip_address("2001:4860:4860::8888"))
 
 
-class TestDirectIPBlocking:
-    """直接IP访问拦截."""
+# ── 直接 IP 访问拦截 ────────────────────────────────────────────────────────
+
+
+class TestDirectIPAccess:
+    """直接 IP 访问控制（ALLOW_DIRECT_IP 开关）."""
 
     def test_direct_ipv4_blocked_by_default(self):
-        """默认禁止直接IP访问."""
+        """默认禁止直接 IP 访问."""
         with pytest.raises(UrlSecurityError, match="禁止直接 IP 访问"):
             validate_url_safety("https://8.8.8.8/audio.mp3")
 
-    def test_direct_ipv6_blocked_by_default(self):
-        """默认禁止直接IPv6访问."""
-        with pytest.raises(UrlSecurityError, match="禁止直接 IP 访问"):
-            validate_url_safety("https://[2001:4860:4860::8888]/audio.mp3")
+    def test_direct_private_ip_blocked_even_with_flag(self):
+        """ALLOW_DIRECT_IP=true 时私有 IP 仍被 SSRF 拦."""
+        with patch("packages.shared.url_security.ALLOW_DIRECT_IP", True):
+            with pytest.raises(UrlSecurityError):
+                validate_url_safety("https://192.168.1.1/a.mp3")
 
-    def test_direct_ip_allowed_when_flag_set(self):
-        """ALLOW_DIRECT_IP=true时允许公网IP直接访问."""
-        with patch("shared.url_security.ALLOW_DIRECT_IP", True):
-            # 公网IP应该通过
-            with patch("shared.url_security._check_ssrf_ip") as mock_check:
-                result = validate_url_safety("https://8.8.8.8/audio.mp3")
-                assert result == "https://8.8.8.8/audio.mp3"
+    def test_direct_ip_allowed_when_flag_on(self):
+        """ALLOW_DIRECT_IP=true 时公网 IP 通过."""
+        with patch("packages.shared.url_security.ALLOW_DIRECT_IP", True):
+            # 用 mock 绕过 DNS 解析路径，走 IP 分支
+            with patch("packages.shared.url_security._check_ssrf_ip") as mock_check:
+                result = validate_url_safety("https://8.8.8.8/a.mp3")
+                assert "8.8.8.8" in result
                 mock_check.assert_called_once()
 
-    def test_direct_private_ip_blocked_even_with_flag(self):
-        """即使ALLOW_DIRECT_IP=true，私有IP仍被SSRF检查拦截."""
-        with patch("shared.url_security.ALLOW_DIRECT_IP", True):
-            with pytest.raises(UrlSecurityError, match="内网地址"):
-                validate_url_safety("https://192.168.1.1/audio.mp3")
+
+# ── 魔数校验补充覆盖 ────────────────────────────────────────────────────────
 
 
-class TestTrustedDomain:
-    """_is_trusted_domain 可信域名匹配."""
+class TestMagicNumberExtended:
+    """魔数校验补充：更多格式 + 边界场景."""
 
-    def test_exact_match(self):
-        """精确匹配."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
-            assert _is_trusted_domain("example.com") is True
-
-    def test_subdomain_match(self):
-        """子域名匹配."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
-            assert _is_trusted_domain("cdn.example.com") is True
-
-    def test_nested_subdomain_match(self):
-        """多级子域名匹配."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
-            assert _is_trusted_domain("a.b.c.example.com") is True
-
-    def test_no_match(self):
-        """不匹配的域名."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
-            assert _is_trusted_domain("other.com") is False
-
-    def test_domain_containing_but_not_subdomain(self):
-        """域名包含但不是子域名."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com"}):
-            assert _is_trusted_domain("fake-example.com") is False
-
-    def test_case_insensitive(self):
-        """大小写不敏感."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", {"Example.COM"}):
-            assert _is_trusted_domain("cdn.example.com") is True
-
-    def test_empty_trusted_domains(self):
-        """空白名单时全部返回False."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", set()):
-            assert _is_trusted_domain("anything.com") is False
-
-    def test_multiple_trusted_domains(self):
-        """多个可信域名."""
-        with patch("shared.url_security.TRUSTED_DOMAINS", {"example.com", "aliyuncs.com"}):
-            assert _is_trusted_domain("bucket.oss-cn-hangzhou.aliyuncs.com") is True
-            assert _is_trusted_domain("cdn.example.com") is True
-            assert _is_trusted_domain("unknown.com") is False
-
-
-class TestIsUrlSafe:
-    """is_url_safe 便捷函数."""
-
-    def test_safe_url_returns_true(self):
-        """安全URL返回True."""
-        with patch("shared.url_security._check_ssrf_domain"):
-            assert is_url_safe("https://example.com/a.mp3") is True
-
-    def test_unsafe_url_returns_false(self):
-        """不安全URL返回False."""
-        assert is_url_safe("ftp://example.com/a.mp3") is False
-
-    def test_empty_url_returns_false(self):
-        """空URL返回False."""
-        assert is_url_safe("") is False
-
-    def test_does_not_raise(self):
-        """不抛异常."""
+    def test_aac_adts_mpeg4(self):
+        """AAC ADTS MPEG-4 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"\xff\xf1" + b"\x00" * 50)
+            tmp = f.name
         try:
-            is_url_safe("not a url at all")
-        except Exception:
-            pytest.fail("is_url_safe should not raise exceptions")
-
-
-class TestMagicNumberValidation:
-    """_validate_magic_number 文件魔数校验."""
-
-    def test_valid_mp3_id3v2(self):
-        """MP3 ID3v2标签魔数通过."""
-        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
-            f.write(b"ID3" + b"\x00" * 100)
-            tmp_path = f.name
-        try:
-            _validate_magic_number(tmp_path, {"audio/mpeg"})  # 不抛异常即通过
+            _validate_magic_number(tmp, {"audio/aac"})
         finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
 
-    def test_valid_wav(self):
-        """WAV文件魔数通过."""
-        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
-            # RIFF + WAVE
-            f.write(b"RIFF" + b"\x00" * 4 + b"WAVE" + b"\x00" * 100)
-            tmp_path = f.name
+    def test_m4a_ftyp_magic(self):
+        """M4A ftyp 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"\x00\x00\x00\x20ftypM4A " + b"\x00" * 50)
+            tmp = f.name
         try:
-            _validate_magic_number(tmp_path, {"audio/wav"})  # 不抛异常即通过
+            _validate_magic_number(tmp, {"audio/x-m4a"})
         finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
 
-    def test_valid_png(self):
-        """PNG图片魔数通过."""
-        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
-            f.write(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
-            tmp_path = f.name
+    def test_webp_riff_webp(self):
+        """WebP RIFF+WEBP 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"RIFF\x00\x00\x00\x00WEBP" + b"\x00" * 50)
+            tmp = f.name
         try:
-            _validate_magic_number(tmp_path, {"image/png"})  # 不抛异常即通过
+            _validate_magic_number(tmp, {"image/webp"})
         finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
 
-    def test_valid_jpeg(self):
-        """JPEG图片魔数通过."""
-        with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as f:
-            f.write(b"\xff\xd8\xff" + b"\x00" * 100)
-            tmp_path = f.name
+    def test_video_mp4_magic(self):
+        """video/mp4 ftyp 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"\x00\x00\x00\x20ftypmp42" + b"\x00" * 50)
+            tmp = f.name
         try:
-            _validate_magic_number(tmp_path, {"image/jpeg"})  # 不抛异常即通过
+            _validate_magic_number(tmp, {"video/mp4"})
         finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
 
-    def test_valid_gif87a(self):
-        """GIF87a通过."""
-        with tempfile.NamedTemporaryFile(suffix=".gif", delete=False) as f:
-            f.write(b"GIF87a" + b"\x00" * 100)
-            tmp_path = f.name
+    def test_matroska_webm_magic(self):
+        """WebM EBML 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"\x1a\x45\xdf\xa3" + b"\x00" * 50)
+            tmp = f.name
         try:
-            _validate_magic_number(tmp_path, {"image/gif"})  # 不抛异常即通过
+            _validate_magic_number(tmp, {"video/webm"})
         finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
 
-    def test_valid_gif89a(self):
-        """GIF89a通过."""
-        with tempfile.NamedTemporaryFile(suffix=".gif", delete=False) as f:
-            f.write(b"GIF89a" + b"\x00" * 100)
-            tmp_path = f.name
+    def test_bmp_magic(self):
+        """BMP BM 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"BM" + b"\x00" * 50)
+            tmp = f.name
         try:
-            _validate_magic_number(tmp_path, {"image/gif"})  # 不抛异常即通过
+            _validate_magic_number(tmp, {"image/bmp"})
         finally:
-            os.unlink(tmp_path)
-
-    def test_valid_ogg(self):
-        """OGG音频通过."""
-        with tempfile.NamedTemporaryFile(suffix=".ogg", delete=False) as f:
-            f.write(b"OggS" + b"\x00" * 100)
-            tmp_path = f.name
-        try:
-            _validate_magic_number(tmp_path, {"audio/ogg"})  # 不抛异常即通过
-        finally:
-            os.unlink(tmp_path)
-
-    def test_invalid_magic_number_rejected(self):
-        """错误魔数被拒绝."""
-        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
-            f.write(b"NOT_A_VALID_FILE" + b"\x00" * 100)
-            tmp_path = f.name
-        try:
-            with pytest.raises(UrlSecurityError, match="文件魔数与允许的 MIME 类型不匹配"):
-                _validate_magic_number(tmp_path, {"audio/mpeg", "image/png"})
-        finally:
-            os.unlink(tmp_path)
-
-    def test_empty_file_rejected(self):
-        """空文件被拒绝."""
-        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
-            tmp_path = f.name
-        try:
-            with pytest.raises(UrlSecurityError, match="文件为空"):
-                _validate_magic_number(tmp_path, {"audio/mpeg"})
-        finally:
-            os.unlink(tmp_path)
-
-    def test_unknown_mime_skipped(self):
-        """未知MIME类型跳过校验."""
-        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
-            f.write(b"random data here")
-            tmp_path = f.name
-        try:
-            # 未知MIME类型没有对应的魔数，应该跳过不阻断
-            _validate_magic_number(tmp_path, {"application/x-unknown-type"})  # 不抛异常即通过
-        finally:
-            os.unlink(tmp_path)
-
-    def test_empty_allowed_mime_skipped(self):
-        """空allowed_mime_types集合直接通过（无魔数可比对）."""
-        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
-            f.write(b"anything")
-            tmp_path = f.name
-        try:
-            _validate_magic_number(tmp_path, set())  # 不抛异常即通过
-        finally:
-            os.unlink(tmp_path)
-
-    def test_multiple_allowed_types_one_matches(self):
-        """多个允许类型，只要一个匹配就通过."""
-        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
-            f.write(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
-            tmp_path = f.name
-        try:
-            _validate_magic_number(tmp_path, {"audio/mpeg", "image/png", "image/jpeg"})
-        finally:
-            os.unlink(tmp_path)
-
-    def test_mp4_ftyp_magic(self):
-        """MP4 ftyp魔数通过."""
-        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:
-            # ftyp在偏移4的位置
-            f.write(b"\x00\x00\x00\x20" + b"ftyp" + b"mp42" + b"\x00" * 100)
-            tmp_path = f.name
-        try:
-            _validate_magic_number(tmp_path, {"video/mp4"})  # 不抛异常即通过
-        finally:
-            os.unlink(tmp_path)
-
-    def test_webp_magic(self):
-        """WebP魔数通过."""
-        with tempfile.NamedTemporaryFile(suffix=".webp", delete=False) as f:
-            f.write(b"RIFF" + b"\x00" * 4 + b"WEBP" + b"\x00" * 100)
-            tmp_path = f.name
-        try:
-            _validate_magic_number(tmp_path, {"image/webp"})  # 不抛异常即通过
-        finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
 
     def test_flac_magic(self):
-        """FLAC魔数通过."""
-        with tempfile.NamedTemporaryFile(suffix=".flac", delete=False) as f:
-            f.write(b"fLaC" + b"\x00" * 100)
-            tmp_path = f.name
+        """FLAC fLaC 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"fLaC" + b"\x00" * 50)
+            tmp = f.name
         try:
-            _validate_magic_number(tmp_path, {"audio/flac"})  # 不抛异常即通过
+            _validate_magic_number(tmp, {"audio/flac"})
         finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
 
-    def test_file_too_short_for_signature(self):
-        """文件太短，不够签名长度时不匹配."""
-        with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
-            f.write(b"ID")  # 只有2字节，不够ID3的3字节
-            tmp_path = f.name
+    def test_ogg_magic(self):
+        """OGG OggS 魔数通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"OggS" + b"\x00" * 50)
+            tmp = f.name
         try:
-            with pytest.raises(UrlSecurityError, match="文件魔数"):
-                _validate_magic_number(tmp_path, {"audio/mpeg"})
+            _validate_magic_number(tmp, {"audio/ogg"})
         finally:
-            os.unlink(tmp_path)
+            os.unlink(tmp)
+
+    def test_read_error_raises_security_error(self):
+        """文件读取失败包装为 UrlSecurityError."""
+        with pytest.raises(UrlSecurityError, match="读取文件头失败"):
+            _validate_magic_number("/nonexistent/path/file.mp3", {"audio/mpeg"})
+
+    def test_multi_type_one_match(self):
+        """多类型白名单，只要一个匹配就通过."""
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"\xff\xd8\xff" + b"\x00" * 50)
+            tmp = f.name
+        try:
+            _validate_magic_number(tmp, {"image/png", "image/jpeg", "image/gif"})
+        finally:
+            os.unlink(tmp)
+
+    def test_application_octet_stream_skipped(self):
+        """application/octet-stream 没有专属魔数，跳过校验."""
+        # 注意：octet-stream 在 _MAGIC_NUMBERS 中没有条目，所以跳过
+        # 但实际白名单中常包含它，所以它的存在不应阻断
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(b"random stuff")
+            tmp = f.name
+        try:
+            # octet-stream + png，png有魔数，png不匹配就会失败
+            # 只有 octet-stream 时应该跳过
+            _validate_magic_number(tmp, {"application/octet-stream"})
+        finally:
+            os.unlink(tmp)
-- 
2.54.0


From a566ef2b4e2aae2ab25cbf7fc9f9836e6925b35e Mon Sep 17 00:00:00 2001
From: CI Bot <ci-bot@xiaoxiajianji.com>
Date: Sat, 25 Jul 2026 11:07:11 +0800
Subject: [PATCH 3/3] style: fix black formatting for wave73 url security tests

---
 tests/unit/test_url_security.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/unit/test_url_security.py b/tests/unit/test_url_security.py
index 04b48482d..c10eac965 100755
--- a/tests/unit/test_url_security.py
+++ b/tests/unit/test_url_security.py
@@ -598,6 +598,7 @@ class TestConstants:
     def test_max_url_length(self):
         assert MAX_URL_LENGTH == 2048
 
+
 # ── SSRF IP 检查详细覆盖 ──────────────────────────────────────────────────────
 
 
-- 
2.54.0