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

tests/test_scheduler.py

@@ -1,3 +1,9 @@
+"""调度器单元测试。
+
+覆盖拓扑排序、任务执行成功/失败分支、输入引用解析、MIME 推断以及
+后台轮询线程的启动与停止。
+"""
+
 import time
 from pathlib import Path
 
@@ -15,10 +21,12 @@ from wov_sdk.models import (
 
 
 def _db(tmp_path) -> Database:
+    """在临时目录创建独立数据库。"""
     return Database(tmp_path / "wov.db")
 
 
 def _echo_definition() -> WorkflowDefinition:
+    """构造引用 Echo 节点的单步骤工作流定义。"""
     return WorkflowDefinition(
         name="echo-flow",
         version=1,
@@ -36,6 +44,7 @@ def _echo_definition() -> WorkflowDefinition:
 
 
 def test_topological_sort() -> None:
+    """验证 DAG 排序保持依赖顺序，并拒绝环与未知边。"""
     definition = WorkflowDefinition(
         name="dag",
         version=1,
@@ -80,6 +89,7 @@ def test_topological_sort() -> None:
 
 
 def test_execute_echo_workflow(tmp_path) -> None:
+    """验证排队任务可被完整执行并登记全部产物。"""
     db = _db(tmp_path)
     input_file = tmp_path / "input.txt"
     input_file.write_text("hello scheduler", encoding="utf-8")
@@ -117,6 +127,7 @@ def test_execute_echo_workflow(tmp_path) -> None:
 
 
 def test_execute_run_missing_workflow(tmp_path, monkeypatch) -> None:
+    """验证工作流记录缺失时任务被标记为失败。"""
     db = _db(tmp_path)
     db.upsert_workflow({"id": "flow", "name": "Flow", "published": 1, "latest_version": 1})
     now = "2026-01-01T00:00:00+00:00"
@@ -142,6 +153,7 @@ def test_execute_run_missing_workflow(tmp_path, monkeypatch) -> None:
 
 
 def test_execute_run_missing_version(tmp_path) -> None:
+    """验证版本记录缺失时任务被标记为失败。"""
     db = _db(tmp_path)
     db.upsert_workflow({"id": "flow", "name": "Flow", "published": 1, "latest_version": 1})
     now = "2026-01-01T00:00:00+00:00"
@@ -166,6 +178,7 @@ def test_execute_run_missing_version(tmp_path) -> None:
 
 
 def test_execute_run_missing_node(tmp_path) -> None:
+    """验证未注册节点被调用时任务失败。"""
     db = _db(tmp_path)
     definition = WorkflowDefinition(
         name="bad",
@@ -204,6 +217,7 @@ def test_execute_run_missing_node(tmp_path) -> None:
 
 
 def test_resolve_ref_and_mime(tmp_path) -> None:
+    """验证输入引用解析、MIME 推断与文件大小读取。"""
     db = _db(tmp_path)
     manager = NodeManager(db)
     scheduler = WorkflowScheduler(db, manager, tmp_path / "storage")
@@ -230,6 +244,7 @@ def test_resolve_ref_and_mime(tmp_path) -> None:
 
 
 def test_execute_unknown_or_non_queued_run(tmp_path) -> None:
+    """验证未知任务或非排队任务会被忽略。"""
     db = _db(tmp_path)
     db.upsert_workflow({"id": "flow", "name": "Flow", "published": 1, "latest_version": 1})
     now = "2026-01-01T00:00:00+00:00"
@@ -255,6 +270,7 @@ def test_execute_unknown_or_non_queued_run(tmp_path) -> None:
 
 
 def test_execute_missing_input(tmp_path) -> None:
+    """验证输入引用无法解析时任务失败。"""
     db = _db(tmp_path)
     definition = WorkflowDefinition(
         name="missing-input",
@@ -293,6 +309,7 @@ def test_execute_missing_input(tmp_path) -> None:
 
 
 def test_execute_node_failed_response(tmp_path) -> None:
+    """验证节点返回 failed 时任务被标记为失败。"""
     db = _db(tmp_path)
     manifest = NodeManifest(
         id="fail-node",
@@ -340,6 +357,7 @@ def test_execute_node_failed_response(tmp_path) -> None:
 
 
 def test_scheduler_start_stop_loop(tmp_path) -> None:
+    """验证调度线程可重复启动并正常停止。"""
     db = _db(tmp_path)
     manager = NodeManager(db)
     scheduler = WorkflowScheduler(db, manager, tmp_path / "storage", interval_seconds=0.05)
@@ -353,6 +371,7 @@ def test_scheduler_start_stop_loop(tmp_path) -> None:
 
 
 def test_scheduler_background_executes_queued_run(tmp_path) -> None:
+    """验证后台线程会自动执行排队中的任务。"""
     db = _db(tmp_path)
     input_file = tmp_path / "input.txt"
     input_file.write_text("background", encoding="utf-8")