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

app/schemas.py

@@ -1,3 +1,9 @@
+"""FastAPI 请求/响应 schema。
+
+使用 Pydantic 模型校验管理 API 的 JSON 请求体，并把请求数据转换为 SDK
+协议模型。
+"""
+
 from __future__ import annotations
 
 from typing import Any
@@ -8,6 +14,8 @@ from wov_sdk.models import NodeManifest
 
 
 class NodeCreate(BaseModel):
+    """节点注册请求体，字段与 NodeManifest 保持一致。"""
+
     id: str = Field(min_length=1)
     name: str = Field(min_length=1)
     version: str = Field(min_length=1)
@@ -23,6 +31,7 @@ class NodeCreate(BaseModel):
     keep_warm: bool = False
 
     def to_manifest(self) -> NodeManifest:
+        """转换为 SDK 的 NodeManifest 对象，供注册与校验使用。"""
         return NodeManifest(
             id=self.id,
             name=self.name,
@@ -41,13 +50,20 @@ class NodeCreate(BaseModel):
 
 
 class InvokePayload(BaseModel):
+    """管理后台手动调用节点的请求体。"""
+
+    # 默认 run_id 便于快速联调，正式运行时会由调度器生成。
     run_id: str = Field(default_factory=lambda: "run_admin")
     inputs: dict[str, Any] = Field(default_factory=dict)
     params: dict[str, Any] = Field(default_factory=dict)
 
 
 class WorkflowCreate(BaseModel):
+    """创建工作流或新增版本的请求体。"""
+
+    # 缺省时由后端根据名称生成 slug ID。
     id: str | None = None
     name: str = Field(min_length=1)
     description: str = ""
+    # DAG 原始字典，后端会解析并校验为 WorkflowDefinition。
     definition: dict[str, Any]