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

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: