docs: 为全部13个源码模块和5个测试文件添加简体中文注释

- 每个文件补充模块级 docstring、类/函数 docstring、关键逻辑行内注释
- 注释风格："中文说明" 或 # 中文说明
- 代码结构和逻辑完全不变

tests/test_active_plate_member.py

@@ -1,3 +1,10 @@
+"""测试活动打印板成员（Active Plate Member）的 3MF 输出行为。
+
+验证内容：
+- write_output_3mf 正确保留配置中指定的打印板 G-code 成员
+- ZIP 压缩级别参数生效并正确裁剪
+- 预览图拼合时仅使用前 9 个唯一输入文件
+"""
 from __future__ import annotations
 
 import hashlib
@@ -23,13 +30,17 @@ except Exception:  # pragma: no cover
 
 
 class ActivePlateMemberTest(unittest.TestCase):
+    """测试写入输出 3MF 时活动打印板成员的正确保留与压缩行为。"""
+
     def test_write_output_preserves_configured_plate_member(self) -> None:
+        """验证 write_output_3mf 保留配置中指定打印板对应的 G-code 成员。"""
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
             source_3mf = root / "plate2.3mf"
             output_3mf = root / "out.3mf"
-            self.write_plate2_archive(source_3mf)
+            self.write_plate2_archive(source_3mf)  # 创建含 plate_2 的测试 3MF
 
+            # 打开源归档，校验 plate_2 被正确识别
             with zipfile.ZipFile(source_3mf, "r") as archive:
                 self.assertEqual(read_model_settings_gcode_members(archive), ["Metadata/plate_2.gcode"])
                 self.assertEqual(resolve_output_gcode_member(archive, "Metadata/plate_2.gcode"), "Metadata/plate_2.gcode")
@@ -38,7 +49,7 @@ class ActivePlateMemberTest(unittest.TestCase):
                     {"Metadata/plate_2.png", "Metadata/plate_2_small.png"},
                 )
 
-            gcode_bytes = b"G1 X1\n"
+            gcode_bytes = b"G1 X1\n"  # 替换用的 G-code 内容
             sources = [
                 PlateSource(
                     source_3mf=source_3mf,
@@ -52,8 +63,9 @@ class ActivePlateMemberTest(unittest.TestCase):
                 add_preview_label=False,
                 apply_gcode_patches=False,
             )
-            md5 = write_output_3mf(source_3mf, output_3mf, gcode_bytes, sources, options)
+            md5 = write_output_3mf(source_3mf, output_3mf, gcode_bytes, sources, options)  # 执行打包输出
 
+            # 校验输出归档中仅包含 plate_2 的 G-code，且 MD5 正确
             with zipfile.ZipFile(output_3mf, "r") as archive:
                 names = set(archive.namelist())
                 self.assertIn("Metadata/plate_2.gcode", names)
@@ -64,6 +76,7 @@ class ActivePlateMemberTest(unittest.TestCase):
                 self.assertEqual(md5, hashlib.md5(gcode_bytes).hexdigest())
 
     def test_write_output_honors_zip_compression_level(self) -> None:
+        """验证 ZIP 压缩级别参数生效：压缩级别越高，压缩后文件越小。"""
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
             source_3mf = root / "plate2.3mf"
@@ -77,8 +90,10 @@ class ActivePlateMemberTest(unittest.TestCase):
                     gcode_text="G1 X0\n",
                 )
             ]
+            # 大量重复 G-code 以便观察压缩效果
             gcode_bytes = (b"G1 X123.456 Y789.012 E0.03456 ; repeated movement\n" * 20000)
 
+            # 分别以压缩级别 1 和 7 输出
             for output_3mf, zip_level in ((level_1_output, 1), (level_7_output, 7)):
                 options = BuildOptions(
                     swap_gcode="",
@@ -89,6 +104,7 @@ class ActivePlateMemberTest(unittest.TestCase):
                 )
                 write_output_3mf(source_3mf, output_3mf, gcode_bytes, sources, options)
 
+            # 比较两个输出文件的压缩后大小：级别 7 应更小
             with zipfile.ZipFile(level_1_output, "r") as level_1_archive, zipfile.ZipFile(level_7_output, "r") as level_7_archive:
                 level_1_info = level_1_archive.getinfo("Metadata/plate_2.gcode")
                 level_7_info = level_7_archive.getinfo("Metadata/plate_2.gcode")
@@ -97,14 +113,17 @@ class ActivePlateMemberTest(unittest.TestCase):
                 self.assertLess(level_7_info.compress_size, level_1_info.compress_size)
 
     def test_zip_compression_level_is_clamped(self) -> None:
-        self.assertEqual(normalized_zip_compress_level(None), 7)
-        self.assertEqual(normalized_zip_compress_level(0), 1)
-        self.assertEqual(normalized_zip_compress_level(10), 9)
+        """验证压缩级别参数被正确裁剪到合法范围 [1, 9]。"""
+        self.assertEqual(normalized_zip_compress_level(None), 7)  # 默认值 → 7
+        self.assertEqual(normalized_zip_compress_level(0), 1)  # 低于下限 → 1
+        self.assertEqual(normalized_zip_compress_level(10), 9)  # 超出上限 → 9
 
     def test_preview_composite_uses_first_nine_unique_input_files(self) -> None:
+        """验证预览图拼合仅使用前 9 个不重复的输入文件，第 10 个被排除。"""
         if Image is None:
             self.skipTest("Pillow is not installed")
 
+        # 10 种不同颜色，用于验证拼合结果
         colors = [
             (255, 0, 0, 255),
             (0, 0, 255, 255),
@@ -121,6 +140,7 @@ class ActivePlateMemberTest(unittest.TestCase):
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
             sources: list[PlateSource] = []
+            # 为每种颜色创建一个独立的 3MF 源文件
             for index, color in enumerate(colors):
                 source_3mf = root / f"source_{index}.3mf"
                 self.write_plate2_archive(source_3mf, image_color=color, image_size=300)
@@ -132,6 +152,7 @@ class ActivePlateMemberTest(unittest.TestCase):
                     )
                 )
 
+            # 验证 select_preview_sources 返回恰好 9 个源
             selected = select_preview_sources(sources)
             self.assertEqual(len(selected), 9)
             self.assertEqual(selected[-1].source_3mf.name, "source_8.3mf")
@@ -140,16 +161,18 @@ class ActivePlateMemberTest(unittest.TestCase):
             options = BuildOptions(
                 swap_gcode="",
                 output_3mf=output_3mf,
-                add_preview_label=True,
+                add_preview_label=True,  # 启用预览标签生成
                 apply_gcode_patches=False,
             )
             write_output_3mf(sources[0].source_3mf, output_3mf, b"G1 X1\n", sources, options)
 
+            # 读取拼合后的预览图
             with zipfile.ZipFile(output_3mf, "r") as archive:
                 image_bytes = archive.read("Metadata/plate_2.png")
 
             import io
 
+            # 在拼合图像的 9 个采样点处检测颜色
             image = Image.open(io.BytesIO(image_bytes)).convert("RGBA")
             sampled_colors = {
                 image.getpixel((50, 50)),
@@ -162,11 +185,19 @@ class ActivePlateMemberTest(unittest.TestCase):
                 image.getpixel((150, 250)),
                 image.getpixel((250, 250)),
             }
+            # 前 9 种颜色全部出现，第 10 种不出现
             self.assertTrue(set(colors[:9]).issubset(sampled_colors))
             self.assertNotIn(colors[9], sampled_colors)
 
     @staticmethod
     def write_plate2_archive(path: Path, image_color: tuple[int, int, int, int] | None = None, image_size: int = 128) -> None:
+        """创建仅含 plate_2 有效 G-code 成员及其预览图的 3MF 测试归档。
+
+        Args:
+            path: 输出 3MF 文件路径
+            image_color: 预览图填充颜色（RGBA），None 则写入占位字节
+            image_size: 预览图尺寸（正方形）
+        """
         model_settings = """<?xml version="1.0" encoding="UTF-8"?>
 <config>
   <plate>
@@ -192,11 +223,13 @@ class ActivePlateMemberTest(unittest.TestCase):
             archive.writestr("Metadata/plate_2.gcode", "G1 X0\n")
             archive.writestr("Metadata/plate_2.gcode.md5", "old")
             if image_color is None or Image is None:
+                # 无 Pillow 或不指定颜色 → 写入占位字节
                 archive.writestr("Metadata/plate_2.png", b"png")
                 archive.writestr("Metadata/plate_2_small.png", b"png")
             else:
                 import io
 
+                # 生成纯色 PNG 预览图及其缩略图
                 image = Image.new("RGBA", (image_size, image_size), image_color)
                 output = io.BytesIO()
                 image.save(output, format="PNG")