docs: 为全部代码补充中文注释并加入 AGENTS 注释规范

tests/test_llm_node.py

@@ -1,3 +1,8 @@
+"""LLM 翻译节点测试。
+
+覆盖真实 HTTP 服务调用、超时配置、SRT 回填、异常与入口点启动等路径。
+"""
+
 import json
 import runpy
 import threading
@@ -11,7 +16,10 @@ from wov_sdk.models import InvokeRequest
 
 
 class FakeUrlOpenResponse:
+    """模拟 urllib 响应对象，提供固定 LLM 译文内容。"""
+
     def __init__(self, content: str) -> None:
+        # 预编码为 Chat Completions 风格的 JSON 响应体。
         self._payload = json.dumps(
             {"choices": [{"message": {"content": content}}]}
         ).encode("utf-8")
@@ -27,6 +35,7 @@ class FakeUrlOpenResponse:
 
 
 def _make_srt(tmp_path, count=5) -> Path:
+    """生成标准 SRT 测试文件，文本行为“原文字幕N”。"""
     lines = []
     for index in range(count):
         lines.extend(
@@ -43,6 +52,7 @@ def _make_srt(tmp_path, count=5) -> Path:
 
 
 def test_translate_lines_via_fake_api(monkeypatch) -> None:
+    """验证通过真实 HTTP 服务器调用 LLM 接口并保持行顺序。"""
     class Handler(BaseHTTPRequestHandler):
         def do_POST(self) -> None:
             length = int(self.headers.get("Content-Length", "0"))
@@ -88,6 +98,7 @@ def test_translate_lines_via_fake_api(monkeypatch) -> None:
 
 
 def test_translate_lines_api_error(monkeypatch) -> None:
+    """验证 LLM 接口不可用时抛出 URLError。"""
     def fail_open(request, timeout):
         raise urllib.error.URLError("api down")
 
@@ -100,6 +111,7 @@ def test_translate_lines_api_error(monkeypatch) -> None:
 
 
 def test_translate_lines_default_timeout(monkeypatch) -> None:
+    """验证未配置超时时使用默认 600 秒。"""
     captured = {}
 
     def fake_open(request, timeout):
@@ -116,6 +128,7 @@ def test_translate_lines_default_timeout(monkeypatch) -> None:
 
 
 def test_translate_lines_env_timeout(monkeypatch) -> None:
+    """验证 LLM_TIMEOUT_SECONDS 环境变量可覆盖超时。"""
     captured = {}
 
     def fake_open(request, timeout):
@@ -132,6 +145,7 @@ def test_translate_lines_env_timeout(monkeypatch) -> None:
 
 
 def test_invoke_success(tmp_path, monkeypatch) -> None:
+    """验证成功调用会把译文回填到 SRT 并输出 cn.srt。"""
     source = _make_srt(tmp_path)
 
     def fake_translate(lines, params):
@@ -153,6 +167,7 @@ def test_invoke_success(tmp_path, monkeypatch) -> None:
 
 
 def test_invoke_pads_short_translation(tmp_path, monkeypatch) -> None:
+    """验证译文行数不足时用空行补齐，保持 SRT 结构完整。"""
     source = _make_srt(tmp_path, count=3)
     monkeypatch.setattr(
         "wov_node_llm.__main__.translate_lines",
@@ -170,6 +185,7 @@ def test_invoke_pads_short_translation(tmp_path, monkeypatch) -> None:
 
 
 def test_invoke_missing_input(tmp_path) -> None:
+    """验证缺少 srt_uri 时返回失败。"""
     response = invoke(
         InvokeRequest(
             run_id="run_3",
@@ -182,6 +198,7 @@ def test_invoke_missing_input(tmp_path) -> None:
 
 
 def test_invoke_missing_file(tmp_path) -> None:
+    """验证 SRT 文件不存在时返回失败。"""
     response = invoke(
         InvokeRequest(
             run_id="run_4",
@@ -194,6 +211,7 @@ def test_invoke_missing_file(tmp_path) -> None:
 
 
 def test_entrypoint(monkeypatch) -> None:
+    """验证 python -m wov_node_llm 会加载 llm-translate manifest。"""
     module_path = Path(__file__).resolve().parent.parent / "wov_node_llm" / "__main__.py"
     captured = {}