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

tests/test_db.py

@@ -1,3 +1,9 @@
+"""数据库层单元测试。
+
+直接对 Database 方法调用真实 SQLite 路径，覆盖节点、实例、工作流、
+版本、任务与产物的增删改查。
+"""
+
 from pathlib import Path
 
 from app.db import Database
@@ -5,6 +11,7 @@ from wov_sdk.models import NodeManifest
 
 
 def manifest() -> NodeManifest:
+    """构造最小合法节点 manifest 供 CRUD 测试复用。"""
     return NodeManifest(
         id="echo",
         name="Echo",
@@ -16,6 +23,7 @@ def manifest() -> NodeManifest:
 
 
 def test_node_crud(tmp_path) -> None:
+    """验证节点的注册、覆盖更新与删除。"""
     db = Database(tmp_path / "wov.db")
     assert db.get_node("echo") is None
     assert db.list_nodes() == []
@@ -34,6 +42,7 @@ def test_node_crud(tmp_path) -> None:
 
 
 def test_instance_crud(tmp_path) -> None:
+    """验证节点实例记录的插入、状态更新与删除。"""
     db = Database(tmp_path / "wov.db")
     db.upsert_node(manifest())
     instance = {
@@ -59,6 +68,7 @@ def test_instance_crud(tmp_path) -> None:
 
 
 def test_workflow_crud(tmp_path) -> None:
+    """验证工作流概要的插入、发布标记更新与删除。"""
     db = Database(tmp_path / "wov.db")
     workflow = {
         "id": "demo",
@@ -79,6 +89,7 @@ def test_workflow_crud(tmp_path) -> None:
 
 
 def test_workflow_versions(tmp_path) -> None:
+    """验证工作流版本的写入、最新版本查询与列表。"""
     db = Database(tmp_path / "wov.db")
     db.upsert_workflow(
         {"id": "demo", "name": "Demo", "published": 1, "latest_version": 2}
@@ -101,6 +112,7 @@ def test_workflow_versions(tmp_path) -> None:
 
 
 def test_run_and_artifact_crud(tmp_path) -> None:
+    """验证任务与产物的创建、查询、更新与删除。"""
     db = Database(tmp_path / "wov.db")
     db.upsert_workflow({"id": "demo", "name": "Demo", "published": 1, "latest_version": 1})
     now = "2026-01-01T00:00:00+00:00"
@@ -145,6 +157,7 @@ def test_run_and_artifact_crud(tmp_path) -> None:
 
 
 def test_reset_run_clears_error_and_artifacts(tmp_path) -> None:
+    """验证 reset_run 会把失败任务恢复到排队状态并清空旧产物。"""
     db = Database(tmp_path / "wov.db")
     db.upsert_workflow({"id": "demo", "name": "Demo", "published": 1, "latest_version": 1})
     now = "2026-01-01T00:00:00+00:00"