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

tests/test_models.py

@@ -1,3 +1,9 @@
+"""wov_sdk.models 的单元测试。
+
+测试覆盖所有数据模型的 JSON 往返序列化、字段校验和 manifest 文件加载，
+确保协议模型的稳定性。
+"""
+
 import json
 
 import pytest
@@ -15,6 +21,7 @@ from wov_sdk.models import (
 
 
 def valid_manifest() -> NodeManifest:
+    """构造一个覆盖全部字段的合法 NodeManifest，供测试复用。"""
     return NodeManifest(
         id="echo",
         name="Echo",
@@ -33,6 +40,7 @@ def valid_manifest() -> NodeManifest:
 
 
 def test_manifest_round_trip() -> None:
+    """验证 manifest 经过 to_dict/from_dict 后保持原值。"""
     manifest = valid_manifest()
     restored = NodeManifest.from_dict(manifest.to_dict())
     assert restored == manifest
@@ -53,6 +61,7 @@ def test_manifest_round_trip() -> None:
     ],
 )
 def test_manifest_validation(field: str, value: object) -> None:
+    """验证必填字段为空或数值越界时抛出 ValueError。"""
     manifest = valid_manifest()
     setattr(manifest, field, value)
     with pytest.raises(ValueError):
@@ -60,6 +69,7 @@ def test_manifest_validation(field: str, value: object) -> None:
 
 
 def test_manifest_load(tmp_path) -> None:
+    """验证 NodeManifest.load 能从 JSON 文件读取并校验。"""
     path = tmp_path / "node.manifest.json"
     path.write_text(json.dumps(valid_manifest().to_dict()), encoding="utf-8")
     loaded = NodeManifest.load(str(path))
@@ -67,6 +77,7 @@ def test_manifest_load(tmp_path) -> None:
 
 
 def test_invoke_request_round_trip() -> None:
+    """验证 InvokeRequest 的 JSON 往返序列化。"""
     request = InvokeRequest(
         run_id="run_1",
         node_instance_id="ni_1",
@@ -79,12 +90,14 @@ def test_invoke_request_round_trip() -> None:
 
 
 def test_invoke_response_round_trip() -> None:
+    """验证 InvokeResponse 的 JSON 往返序列化。"""
     response = InvokeResponse(status="completed", outputs={"text": "hello"})
     restored = InvokeResponse.from_dict(response.to_dict())
     assert restored == response
 
 
 def test_health_and_progress_serialization() -> None:
+    """验证健康检查和进度事件模型的字典输出。"""
     health = HealthResponse(status="ok", node_id="echo", version="1.0.0")
     assert health.to_dict() == {
         "status": "ok",
@@ -102,6 +115,7 @@ def test_health_and_progress_serialization() -> None:
 
 
 def test_workflow_node_and_edge_round_trip() -> None:
+    """验证工作流节点与边的 JSON 往返序列化。"""
     node = WorkflowNode(
         id="asr",
         node_type="faster-whisper",
@@ -117,6 +131,7 @@ def test_workflow_node_and_edge_round_trip() -> None:
 
 
 def test_workflow_definition_round_trip_and_validation() -> None:
+    """验证完整 DAG 定义可往返序列化并通过校验。"""
     definition = WorkflowDefinition(
         name="demo",
         version=1,
@@ -134,6 +149,7 @@ def test_workflow_definition_round_trip_and_validation() -> None:
 
 
 def test_workflow_definition_invalid() -> None:
+    """验证非法 DAG（空名、版本为 0、重复节点、未知边）被拒绝。"""
     with pytest.raises(ValueError):
         WorkflowDefinition(name="", version=1).validate()
 

tests/test_server.py

@@ -1,3 +1,9 @@
+"""wov_sdk.server 的协议测试。
+
+通过真实 HTTP 请求验证 /health 与 /invoke 端点的正常、404 和 500 分支，
+并验证 run_node 的启动输出格式。
+"""
+
 import json
 import threading
 import urllib.error
@@ -10,6 +16,7 @@ from wov_sdk.server import NodeHTTPServer, create_node_server, run_node
 
 
 def valid_manifest() -> NodeManifest:
+    """构造一个合法的最小 Echo 节点 manifest。"""
     return NodeManifest(
         id="echo",
         name="Echo",
@@ -20,6 +27,7 @@ def valid_manifest() -> NodeManifest:
 
 
 def test_create_node_server_validates_manifest() -> None:
+    """验证空 manifest 在创建服务器前就会被校验拒绝。"""
     with pytest.raises(ValueError):
         create_node_server(
             NodeManifest(
@@ -34,6 +42,7 @@ def test_create_node_server_validates_manifest() -> None:
 
 
 def _post(server: NodeHTTPServer, path: str, body: dict | None = None) -> tuple[int, dict]:
+    """向节点服务器发送 POST 请求并返回状态码与 JSON 响应。"""
     data = json.dumps(body or {}).encode("utf-8")
     request = urllib.request.Request(
         f"http://127.0.0.1:{server.server_address[1]}{path}",
@@ -49,6 +58,7 @@ def _post(server: NodeHTTPServer, path: str, body: dict | None = None) -> tuple[
 
 
 def _get(server: NodeHTTPServer, path: str) -> tuple[int, dict]:
+    """向节点服务器发送 GET 请求并返回状态码与 JSON 响应。"""
     try:
         with urllib.request.urlopen(
             f"http://127.0.0.1:{server.server_address[1]}{path}", timeout=5
@@ -59,6 +69,7 @@ def _get(server: NodeHTTPServer, path: str) -> tuple[int, dict]:
 
 
 def test_http_protocol() -> None:
+    """验证健康检查、正常调用、404 与非法请求体等协议分支。"""
     def handler(request: InvokeRequest) -> InvokeResponse:
         return InvokeResponse(
             status="completed",
@@ -66,6 +77,7 @@ def test_http_protocol() -> None:
         )
 
     server = create_node_server(valid_manifest(), handler)
+    # 在独立线程中运行服务器，主线程执行 HTTP 客户端断言。
     thread = threading.Thread(target=server.serve_forever, daemon=True)
     thread.start()
     try:
@@ -103,6 +115,7 @@ def test_http_protocol() -> None:
 
 
 def test_http_protocol_handler_error() -> None:
+    """验证业务处理函数抛异常时返回 500 与 failed 状态。"""
     def failing_handler(request: InvokeRequest) -> InvokeResponse:
         raise RuntimeError("boom")
 
@@ -130,6 +143,7 @@ def test_http_protocol_handler_error() -> None:
 
 
 def test_run_node(monkeypatch, capsys) -> None:
+    """验证 run_node 打印 WOV_NODE_READY 端口行并进入服务循环。"""
     called = []
 
     def fake_serve_forever(server: NodeHTTPServer) -> None: