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

app/routers/workflows.py

@@ -1,3 +1,9 @@
+"""工作流管理路由。
+
+提供工作流的创建、查询、校验、发布和删除能力。工作流以版本化 DAG 数据保存，
+不写死在业务代码中。
+"""
+
 from __future__ import annotations
 
 import re
@@ -13,17 +19,20 @@ router = APIRouter(prefix="/api/admin/workflows", tags=["workflows"])
 
 
 def _get_db() -> Database:
+    """从应用状态延迟获取数据库实例。"""
     from app.main import app
 
     return app.state.db
 
 
 def _slugify(value: str) -> str:
+    """把工作流名称转换为小写连字符 ID；无有效字符时生成随机 ID。"""
     slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
     return slug or uuid.uuid4().hex[:8]
 
 
 def _validate_definition(raw: dict) -> WorkflowDefinition:
+    """解析并校验 DAG 定义，非法时转换为 422 HTTP 异常。"""
     try:
         definition = WorkflowDefinition.from_dict(raw)
         definition.validate()
@@ -34,6 +43,7 @@ def _validate_definition(raw: dict) -> WorkflowDefinition:
 
 @router.get("")
 def list_workflows(db: Database = Depends(_get_db)) -> list[dict]:
+    """返回全部工作流概要。"""
     return db.list_workflows()
 
 
@@ -42,10 +52,13 @@ def create_workflow(
     payload: WorkflowCreate,
     db: Database = Depends(_get_db),
 ) -> dict:
+    """创建新工作流或为已有工作流追加一个版本。"""
     definition = _validate_definition(payload.definition)
+    # 未显式指定 ID 时由名称生成；已有工作流则版本号递增。
     workflow_id = payload.id or _slugify(payload.name)
     existing = db.get_workflow(workflow_id)
     version = (existing or {}).get("latest_version", 0) + 1
+    # 每次创建都保存新版本，发布操作只切换 published 标记。
     db.upsert_workflow(
         {
             "id": workflow_id,
@@ -67,6 +80,7 @@ def create_workflow(
 
 @router.get("/{workflow_id}")
 def get_workflow(workflow_id: str, db: Database = Depends(_get_db)) -> dict:
+    """返回工作流概要及最新版本定义。"""
     workflow = db.get_workflow(workflow_id)
     if workflow is None:
         raise HTTPException(status_code=404, detail="workflow not found")
@@ -77,6 +91,7 @@ def get_workflow(workflow_id: str, db: Database = Depends(_get_db)) -> dict:
 
 @router.delete("/{workflow_id}")
 def delete_workflow(workflow_id: str, db: Database = Depends(_get_db)) -> dict:
+    """删除工作流及其版本、任务和产物记录。"""
     if db.get_workflow(workflow_id) is None:
         raise HTTPException(status_code=404, detail="workflow not found")
     db.delete_workflow(workflow_id)
@@ -89,6 +104,7 @@ def validate_workflow(
     definition: dict,
     db: Database = Depends(_get_db),
 ) -> dict:
+    """在不保存的情况下校验一份 DAG 定义。"""
     if db.get_workflow(workflow_id) is None:
         raise HTTPException(status_code=404, detail="workflow not found")
     parsed = _validate_definition(definition)
@@ -97,11 +113,13 @@ def validate_workflow(
 
 @router.post("/{workflow_id}/publish")
 def publish_workflow(workflow_id: str, db: Database = Depends(_get_db)) -> dict:
+    """把工作流标记为已发布，使其出现在用户应用中心。"""
     workflow = db.get_workflow(workflow_id)
     if workflow is None:
         raise HTTPException(status_code=404, detail="workflow not found")
     if workflow["latest_version"] == 0:
         raise HTTPException(status_code=422, detail="workflow has no version")
+    # 发布只是状态切换，不修改已保存的版本数据。
     db.upsert_workflow(
         {
             "id": workflow_id,
@@ -116,6 +134,7 @@ def publish_workflow(workflow_id: str, db: Database = Depends(_get_db)) -> dict:
 
 @router.get("/{workflow_id}/versions")
 def list_versions(workflow_id: str, db: Database = Depends(_get_db)) -> list[dict]:
+    """返回工作流全部版本定义。"""
     if db.get_workflow(workflow_id) is None:
         raise HTTPException(status_code=404, detail="workflow not found")
     return db.list_workflow_versions(workflow_id)