bump version to 0.2.6

1.  移除本地setenvs函数，改用封装好的SETENV任务
2.  替换hf下载命令为modelscope下载命令
3.  优化参数命名和默认下载目录逻辑
4.  简化任务编排代码

pyproject.toml

@@ -10,21 +10,24 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Topic :: Software Development :: Libraries :: Application Frameworks",
 ]
-dependencies = ["graphlib_backport >= 1.0.0; python_version < '3.9'"]
+dependencies = [
+    "graphlib_backport >= 1.0.0; python_version < '3.9'",
+    "typing-extensions>=4.13.2",
+]
 description = "Lightweight, type-safe DAG task scheduler with multi-strategy execution."
 keywords = ["async", "dag", "scheduler", "task", "workflow"]
 license = { text = "MIT" }
 name = "pyflowx"
 readme = "README.md"
 requires-python = ">=3.8"
-version = "0.2.3"
+version = "0.2.6"
 
 [project.scripts]
 autofmt     = "pyflowx.cli.autofmt:main"
 bumpversion = "pyflowx.cli.bumpversion:main"
 clr         = "pyflowx.cli.clearscreen:main"
 emlman      = "pyflowx.cli.emlmanager:main"
-envlinux    = "pyflowx.cli.envlinux:main"
+envdev      = "pyflowx.cli.envdev:main"
 envpy       = "pyflowx.cli.envpy:main"
 envqt       = "pyflowx.cli.envqt:main"
 envrs       = "pyflowx.cli.envrs:main"
@@ -146,6 +149,6 @@ select = [
 "**/tests/**" = ["ARG001", "ARG002"]
 
 [tool.pyrefly]
-preset           = "basic"
+preset           = "strict"
 project-includes = ["**/*.ipynb", "**/*.py*"]
 python-version   = "3.8"

src/pyflowx/__init__.py

@@ -84,7 +84,7 @@ from .runner import CliExitCode, CliRunner
 from .storage import JSONBackend, MemoryBackend, StateBackend
 from .task import TaskCmd, TaskEvent, TaskResult, TaskSpec, TaskStatus
 
-__version__ = "0.2.3"
+__version__ = "0.2.6"
 
 __all__ = [
     "IS_LINUX",

src/pyflowx/cli/__init__.py

@@ -1,78 +0,0 @@
-"""CLI 工具模块.
-
-提供各种命令行工具的入口点.
-"""
-
-from __future__ import annotations
-
-# 自动格式化工具
-from pyflowx.cli.autofmt import main as autofmt_main
-from pyflowx.cli.bumpversion import main as bumpversion_main
-from pyflowx.cli.clearscreen import main as clearscreen_main
-
-# EML 邮件管理工具
-from pyflowx.cli.emlmanager import main as emlmanager_main
-
-# EML 邮件管理工具
-from pyflowx.cli.emlmanager import main as emlmanager_web_main
-from pyflowx.cli.envpy import main as envpy_main
-from pyflowx.cli.envqt import main as envqt_main
-from pyflowx.cli.envrs import main as envrs_main
-
-# 文件工具
-from pyflowx.cli.filedate import main as filedate_main
-from pyflowx.cli.filelevel import main as filelevel_main
-from pyflowx.cli.folderback import main as folderback_main
-from pyflowx.cli.folderzip import main as folderzip_main
-
-# Git 工具
-from pyflowx.cli.gittool import main as gittool_main
-
-# 仿真工具
-from pyflowx.cli.lscalc import main as lscalc_main
-
-# 打包工具
-from pyflowx.cli.packtool import main as packtool_main
-
-# PDF 工具
-from pyflowx.cli.pdftool import main as pdftool_main
-
-# 开发工具
-from pyflowx.cli.piptool import main as piptool_main
-from pyflowx.cli.pymake import main as pymake_main
-from pyflowx.cli.screenshot import main as screenshot_main
-from pyflowx.cli.sshcopyid import main as sshcopyid_main
-
-__all__ = [
-    # 自动格式化工具
-    "autofmt_main",
-    "bumpversion_main",
-    "clearscreen_main",
-    # EML 邮件管理工具
-    "emlmanager_main",
-    "emlmanager_web_main",
-    "envpy_main",
-    "envqt_main",
-    "envrs_main",
-    # 文件工具
-    "filedate_main",
-    "filelevel_main",
-    "folderback_main",
-    "folderzip_main",
-    # Git 工具
-    "gittool_main",
-    # 仿真工具
-    "lscalc_main",
-    # 打包工具
-    "packtool_main",
-    # PDF 工具
-    "pdftool_main",
-    # 开发工具
-    "piptool_main",
-    "pymake_main",
-    "screenshot_main",
-    "sshcopyid_main",
-    # 系统工具
-    "taskkill_main",
-    "which_main",
-]

src/pyflowx/cli/autofmt.py

@@ -268,13 +268,13 @@ def main() -> None:
             cmd.extend(["--fix", "--unsafe-fixes"])
         graph = px.Graph.from_specs([px.TaskSpec("ruff_check", cmd=cmd, verbose=True)])
     elif args.command == "doc":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("auto_docstring", fn=auto_add_docstrings, args=(Path(args.root_dir),), verbose=True)]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("auto_docstring", fn=auto_add_docstrings, args=(Path(args.root_dir),), verbose=True)
+        ])
     elif args.command == "sync":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("sync_config", fn=sync_pyproject_config, args=(Path(args.root_dir),), verbose=True)]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("sync_config", fn=sync_pyproject_config, args=(Path(args.root_dir),), verbose=True)
+        ])
     else:
         parser.print_help()
         return

src/pyflowx/cli/bumpversion.py

@@ -212,16 +212,14 @@ def main() -> None:
 
     # 更新所有文件的版本号（使用顺序执行避免竞争条件）
     # 使用相对于 cwd 的路径作为任务名，确保唯一性
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec(
-                f"bump_{file.relative_to(Path.cwd())}".replace("\\", "_").replace("/", "_").replace(".", "_"),
-                fn=bump_file_version,
-                args=(file, part),
-            )
-            for file in all_files
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec(
+            f"bump_{file.relative_to(Path.cwd())}".replace("\\", "_").replace("/", "_").replace(".", "_"),
+            fn=bump_file_version,
+            args=(file, part),
+        )
+        for file in all_files
+    ])
     report = px.run(graph, strategy="sequential")
 
     # 收集新版本号（取第一个成功的结果）
@@ -238,24 +236,28 @@ def main() -> None:
 
     print(f"版本号已更新为: {new_version}")
 
-    # 提交修改
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("git_add", cmd=["git", "add", "."]),
-            px.TaskSpec(
-                "git_commit", cmd=["git", "commit", "-m", f"bump version to {new_version}"], depends_on=["git_add"]
-            ),
-        ]
-    )
-    px.run(graph, strategy="sequential")
+    # 提交修改并创建标签
+    tasks = [
+        px.TaskSpec("git_add", cmd=["git", "add", "."]),
+        px.TaskSpec(
+            "git_commit",
+            cmd=["git", "commit", "-m", f"bump version to {new_version}"],
+            depends_on=("git_add",),
+        ),
+    ]
 
-    # 创建 git tag
     if not args.no_tag:
         tag_name = f"v{new_version}"
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec("git_tag", cmd=["git", "tag", "-a", tag_name, "-m", f"Release {tag_name}"]),
-            ]
+        tasks.append(
+            px.TaskSpec(
+                "git_tag",
+                cmd=["git", "tag", "-a", tag_name, "-m", f"Release {tag_name}"],
+                depends_on=("git_commit",),
+            )
         )
-        px.run(graph, strategy="sequential")
-        print(f"已创建标签: {tag_name}")
+
+    graph = px.Graph.from_specs(tasks)
+    px.run(graph, strategy="sequential")
+
+    if not args.no_tag:
+        print(f"已创建标签: v{new_version}")

src/pyflowx/cli/clearscreen.py

@@ -5,23 +5,11 @@
 
 from __future__ import annotations
 
-import subprocess
-
 import pyflowx as px
-from pyflowx.conditions import Constants
-
-
-def clear_screen() -> None:
-    """使用系统命令清屏."""
-    if Constants.IS_WINDOWS:
-        subprocess.run(["cmd", "/c", "cls"], check=False)
-    else:
-        subprocess.run(["clear"], check=False)
-
-    print("\033[2J\033[H", end="")
+from pyflowx.tasks.system import CLR
 
 
 def main() -> None:
     """清屏工具主函数."""
-    graph = px.Graph.from_specs([px.TaskSpec("clearscreen", fn=clear_screen)])
+    graph = px.Graph.from_specs([CLR()])
     px.run(graph, strategy="thread")

src/pyflowx/cli/emlmanager.py

@@ -88,6 +88,8 @@ class EmailDatabase:
 
     def insert_email(self, email_data: dict[str, Any]) -> bool:
         """插入邮件数据."""
+        assert self.conn, "数据库连接未初始化"
+
         try:
             with self._lock:
                 cursor = self.conn.cursor()
@@ -123,6 +125,8 @@ class EmailDatabase:
         self, keyword: str = "", field: str = "all", limit: int = 100, offset: int = 0
     ) -> list[dict[str, Any]]:
         """搜索邮件."""
+        assert self.conn, "数据库连接未初始化"
+
         with self._lock:
             cursor = self.conn.cursor()
 
@@ -154,6 +158,8 @@ class EmailDatabase:
 
     def get_grouped_emails(self) -> dict[str, list[dict[str, Any]]]:
         """获取按主题分组的邮件."""
+        assert self.conn, "数据库连接未初始化"
+
         with self._lock:
             cursor = self.conn.cursor()
             cursor.execute(f"SELECT * FROM {TABLE_NAME} ORDER BY subject, date_parsed DESC")
@@ -183,6 +189,8 @@ class EmailDatabase:
 
     def get_email_count(self) -> int:
         """获取邮件总数."""
+        assert self.conn, "数据库连接未初始化"
+
         with self._lock:
             cursor = self.conn.cursor()
             cursor.execute(f"SELECT COUNT(*) FROM {TABLE_NAME}")
@@ -190,6 +198,8 @@ class EmailDatabase:
 
     def clear_all(self) -> None:
         """清空所有邮件数据."""
+        assert self.conn, "数据库连接未初始化"
+
         with self._lock:
             cursor = self.conn.cursor()
             cursor.execute(f"DELETE FROM {TABLE_NAME}")
@@ -557,15 +567,13 @@ class EmlManagerHandler(BaseHTTPRequestHandler):
 
         emails = self.db.search_emails(keyword, field, limit, offset)
         total_count = self.db.get_email_count()
-        self._send_json_response(
-            {
-                "emails": emails,
-                "count": len(emails),
-                "total": total_count,
-                "limit": limit,
-                "offset": offset,
-            }
-        )
+        self._send_json_response({
+            "emails": emails,
+            "count": len(emails),
+            "total": total_count,
+            "limit": limit,
+            "offset": offset,
+        })
 
     def _api_get_email(self, query_params: dict[str, list[str]]) -> None:
         """API: 获取单个邮件详情."""
@@ -578,6 +586,10 @@ class EmlManagerHandler(BaseHTTPRequestHandler):
             self._send_json_response({"error": "缺少邮件ID"}, 400)
             return
 
+        if not self.db.conn:
+            self._send_json_response({"error": "数据库连接未初始化"}, 500)
+            return
+
         with self.db._lock:
             cursor = self.db.conn.cursor()
             cursor.execute(f"SELECT * FROM {TABLE_NAME} WHERE id = ?", (int(email_id),))
@@ -630,6 +642,10 @@ class EmlManagerHandler(BaseHTTPRequestHandler):
             if not eml_files:
                 return
 
+            if not self.db.conn:
+                self._send_json_response({"error": "数据库连接未初始化"}, 500)
+                return
+
             # 先批量查询所有已存在的文件
             with self.db._lock:
                 cursor = self.db.conn.cursor()
@@ -1268,6 +1284,10 @@ def main() -> None:
             if eml_files:
                 print(f"发现 {len(eml_files)} 个 EML 文件，开始导入...")
 
+                if not EmlManagerHandler.db.conn:
+                    print("数据库连接未初始化，无法导入邮件")
+                    return
+
                 # 先批量查询所有已存在的文件
                 with EmlManagerHandler.db._lock:
                     cursor = EmlManagerHandler.db.conn.cursor()

src/pyflowx/cli/envdev.py

@@ -0,0 +1,59 @@
+from typing import TypedDict
+
+import pyflowx as px
+
+
+class EnvConfig(TypedDict):
+    """环境配置项."""
+
+    name: str
+    value: str
+    description: str
+
+
+PIP_INDEX_URL_CONFIG: EnvConfig = {
+    "name": "PIP_INDEX_URL",
+    "value": "https://pypi.tuna.tsinghua.edu.cn/simple",
+    "description": "PIP索引URL",
+}
+
+
+# ============================================================================
+# 配置
+# ============================================================================
+
+PIP_INDEX_URLS: dict[str, str] = {
+    "tsinghua": "https://pypi.tuna.tsinghua.edu.cn/simple",
+    "aliyun": "https://mirrors.aliyun.com/pypi/simple/",
+}
+
+PIP_TRUSTED_HOSTS: dict[str, str] = {
+    "tsinghua": "pypi.tuna.tsinghua.edu.cn",
+    "aliyun": "mirrors.aliyun.com",
+}
+
+UV_INDEX_URL: str = "https://mirrors.aliyun.com/pypi/simple/"
+UV_PYTHON_INSTALL_MIRROR: str = "https://registry.npmmirror.com/-/binary/python-build-standalone"
+
+CONDA_MIRROR_URLS: dict[str, list[str]] = {
+    "tsinghua": [
+        "https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/",
+        "https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/",
+        "https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/",
+    ],
+    "aliyun": [
+        "https://mirrors.aliyun.com/anaconda/pkgs/main/",
+        "https://mirrors.aliyun.com/anaconda/pkgs/free/",
+        "https://mirrors.aliyun.com/anaconda/cloud/conda-forge/",
+    ],
+}
+
+
+def main() -> None:
+    """主函数."""
+    # 使用更安全的分步执行方式，便于调试和捕获错误
+    graph = px.Graph.from_specs([
+        px.TaskSpec("download", cmd="curl -sSL https://linuxmirrors.cn/main.sh -o /tmp/linuxmirrors.sh", verbose=True),
+        px.TaskSpec("install", cmd="sudo bash /tmp/linuxmirrors.sh", verbose=True, depends_on=("download",)),
+    ])
+    px.run(graph, strategy="thread")

src/pyflowx/cli/envlinux.py

@@ -1,11 +0,0 @@
-import pyflowx as px
-
-
-def main() -> None:
-    """主函数."""
-    # 使用更安全的分步执行方式，便于调试和捕获错误
-    graph = px.Graph.from_specs([
-        px.TaskSpec("download", cmd="curl -sSL https://linuxmirrors.cn/main.sh -o /tmp/linuxmirrors.sh", verbose=True),
-        px.TaskSpec("install", cmd="sudo bash /tmp/linuxmirrors.sh", verbose=True, depends_on=("download",)),
-    ])
-    px.run(graph, strategy="thread")

src/pyflowx/cli/envrs.py

@@ -39,7 +39,7 @@ RUSTUP_MIRRORS: dict[str, dict[str, str]] = {
 UsableRustVersion = Literal["stable", "nightly", "beta"]
 UsableMirror = Literal["aliyun", "ustc", "tsinghua"]
 
-DEFAULT_RUST_VERSION: str = "stable"
+DEFAULT_RUST_VERSION: UsableRustVersion = "stable"
 DEFAULT_MIRROR: UsableMirror = "tsinghua"
 
 
@@ -136,13 +136,13 @@ def main() -> None:
     args = parser.parse_args()
 
     if args.command == "mirror":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("set_rust_mirror", fn=set_rust_mirror, args=(args.name,), verbose=True)]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("set_rust_mirror", fn=set_rust_mirror, args=(args.name,), verbose=True)
+        ])
     elif args.command == "install":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("install_rust", cmd=["rustup", "toolchain", "install", args.version], verbose=True)]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("install_rust", cmd=["rustup", "toolchain", "install", args.version], verbose=True)
+        ])
     else:
         parser.print_help()
         return

src/pyflowx/cli/filedate.py

@@ -113,27 +113,23 @@ def main() -> None:
     args = parser.parse_args()
 
     if args.command == "add":
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "process_files_date",
-                    fn=process_files_date,
-                    args=([Path(f) for f in args.files],),
-                    kwargs={"clear": False},
-                )
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "process_files_date",
+                fn=process_files_date,
+                args=([Path(f) for f in args.files],),
+                kwargs={"clear": False},
+            )
+        ])
     elif args.command == "clear":
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "process_files_date",
-                    fn=process_files_date,
-                    args=([Path(f) for f in args.files],),
-                    kwargs={"clear": True},
-                )
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "process_files_date",
+                fn=process_files_date,
+                args=([Path(f) for f in args.files],),
+                kwargs={"clear": True},
+            )
+        ])
     else:
         parser.print_help()
         return

src/pyflowx/cli/gittool.py

@@ -33,20 +33,16 @@ def init_sub_dirs() -> None:
     sub_dirs = [subdir for subdir in Path.cwd().iterdir() if subdir.is_dir()]
     for subdir in sub_dirs:
         px.run(
-            px.Graph.from_specs(
-                [
-                    px.TaskSpec(
-                        "init",
-                        cmd=["git", "init"],
-                        conditions=[not_has_git_repo],
-                        cwd=str(subdir),
-                    ),
-                    px.TaskSpec("add", cmd=["git", "add", "."], depends_on=["init"], cwd=str(subdir)),
-                    px.TaskSpec(
-                        "commit", cmd=["git", "commit", "-m", "init commit"], depends_on=["add"], cwd=str(subdir)
-                    ),
-                ]
-            ),
+            px.Graph.from_specs([
+                px.TaskSpec(
+                    "init",
+                    cmd=["git", "init"],
+                    conditions=(not_has_git_repo,),
+                    cwd=subdir,
+                ),
+                px.TaskSpec("add", cmd=["git", "add", "."], depends_on=("init",)),
+                px.TaskSpec("commit", cmd=["git", "commit", "-m", "init commit"], depends_on=("add",)),
+            ]),
         )
 
 
@@ -73,29 +69,23 @@ def main() -> None:
         description="Gittool - Git 执行工具.",
         graphs={
             # 添加并提交
-            "a": px.Graph.from_specs(
-                [
-                    px.TaskSpec("add", cmd=["git", "add", "."], conditions=[has_files]),
-                    px.TaskSpec("commit", cmd=["git", "commit", "-m", "chore: update"], depends_on=["add"]),
-                ]
-            ),
+            "a": px.Graph.from_specs([
+                px.TaskSpec("add", cmd=["git", "add", "."], conditions=(has_files,)),
+                px.TaskSpec("commit", cmd=["git", "commit", "-m", "chore: update"], depends_on=("add",)),
+            ]),
             # 清理
-            "c": px.Graph.from_specs(
-                [
-                    px.TaskSpec("clean", cmd=["git", "clean", "-xfd", *EXCLUDE_CMDS]),
-                    px.TaskSpec("status", cmd=["git", "status", "--porcelain"], depends_on=["clean"]),
-                ]
-            ),
+            "c": px.Graph.from_specs([
+                px.TaskSpec("clean", cmd=["git", "clean", "-xfd", *EXCLUDE_CMDS]),
+                px.TaskSpec("status", cmd=["git", "status", "--porcelain"], depends_on=("clean",)),
+            ]),
             # 初始化、添加并提交
-            "i": px.Graph.from_specs(
-                [
-                    px.TaskSpec("init", cmd=["git", "init"], conditions=[not_has_git_repo]),
-                    px.TaskSpec("add", cmd=["git", "add", "."], depends_on=["init"], conditions=[has_files]),
-                    px.TaskSpec(
-                        "commit", cmd=["git", "commit", "-m", "init commit"], depends_on=["add"], conditions=[has_files]
-                    ),
-                ]
-            ),
+            "i": px.Graph.from_specs([
+                px.TaskSpec("init", cmd=["git", "init"], conditions=(not_has_git_repo,)),
+                px.TaskSpec("add", cmd=["git", "add", "."], depends_on=("init",), conditions=(has_files,)),
+                px.TaskSpec(
+                    "commit", cmd=["git", "commit", "-m", "init commit"], depends_on=("add",), conditions=(has_files,)
+                ),
+            ]),
             # 初始化子目录
             "isub": px.Graph.from_specs([isub]),
             # 推送

src/pyflowx/cli/hfdownload.py

@@ -1,86 +1,50 @@
 import argparse
-import os
 from pathlib import Path
 from typing import Literal, get_args
 
 import pyflowx as px
+from pyflowx.tasks.system import SETENV
 
 HFDownloadType = Literal["model", "dataset", "space"]
 
 
-def setenvs():
-    """设置 HuggingFace mirror 环境变量."""
-    os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
-
-
 def main():
     parser = argparse.ArgumentParser(description="Download a model from HuggingFace.")
-    parser.add_argument("dataset_name", type=str, help="HuggingFace dataset name.")
+    parser.add_argument("name", help="Target name.")
     parser.add_argument(
-        "--type",
-        type=str,
-        nargs="?",
-        default="dataset",
-        choices=get_args(HFDownloadType),
-        help="HuggingFace dataset type.",
+        "--type", "-t", nargs="?", default="model", choices=get_args(HFDownloadType), help="Target type."
     )
-    parser.add_argument("--use-hfd", action="store_true", help="Use HFD tool to download dataset.")
+    parser.add_argument("--dir", default=None, help="Download directory.")
     args = parser.parse_args()
 
-    if not args.dataset_name:
-        parser.error("dataset_name is required")
+    if not args.name:
+        parser.error("name is required")
 
-    dataset_name = args.dataset_name
+    target_name = args.name
 
     # 创建下载目录
-    download_dir = Path.cwd() / dataset_name
+    if args.dir:
+        download_dir = Path(args.dir)
+    else:
+        download_dir = Path.home() / ".models" / target_name.split("/")[-1]
     download_dir.mkdir(parents=True, exist_ok=True)
 
-    if args.use_hfd:
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(name="setenvs", fn=setenvs, verbose=True),
-                px.TaskSpec(
-                    name="download_hfd",
-                    cmd=["wget", "https://hf-mirror.com/hfd/hfd.sh"],
-                    depends_on=["setenvs"],
-                    verbose=True,
-                ),
-                px.TaskSpec(
-                    name="chmod_hfd",
-                    cmd=["chmod", "a+x", "hfd.sh"],
-                    depends_on=["download_hfd"],
-                    verbose=True,
-                ),
-                px.TaskSpec(
-                    name="run_hfd",
-                    cmd=["./hfd.sh", dataset_name, args.type],
-                    depends_on=["chmod_hfd"],
-                    verbose=True,
-                ),
-            ]
-        )
-    else:
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(name="setenvs", fn=setenvs, verbose=True),
-                px.TaskSpec(
-                    name="download",
-                    cmd=[
-                        "uvx",
-                        "hf",
-                        "download",
-                        "--repo-type",
-                        args.type,
-                        "--force-download",
-                        dataset_name,
-                        "--local-dir",
-                        str(Path.cwd() / dataset_name),
-                    ],
-                    depends_on=["setenvs"],
-                    verbose=True,
-                ),
-            ]
-        )
+    graph = px.Graph.from_specs([
+        SETENV("HF_ENDPOINT", "https://hf-mirror.com"),
+        px.TaskSpec(
+            name="download",
+            cmd=[
+                "uvx",
+                "modelscope",
+                "download",
+                f"--{args.type}",
+                target_name,
+                "--local_dir",
+                str(download_dir),
+            ],
+            depends_on=("setenv_hf_endpoint",),
+            verbose=True,
+        ),
+    ])
 
     px.run(graph, strategy="thread", verbose=True)

src/pyflowx/cli/pdftool.py

@@ -146,7 +146,7 @@ def pdf_extract_text(input_path: Path, output_path: Path) -> None:
     doc = fitz.open(str(input_path))
     text = ""
     for page in doc:
-        text += page.get_text() + "\n\n"
+        text += str(page.get_text()) + "\n\n"
     doc.close()
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
@@ -164,6 +164,7 @@ def pdf_extract_images(input_path: Path, output_dir: Path) -> None:
     output_dir.mkdir(parents=True, exist_ok=True)
 
     image_count = 0
+    # pyrefly: ignore [bad-argument-type]
     for page_num, page in enumerate(doc):
         images = page.get_images(full=True)
         for img_idx, img in enumerate(images):
@@ -249,9 +250,13 @@ def pdf_info(input_path: Path) -> None:
     doc = fitz.open(str(input_path))
     print(f"文件: {input_path}")
     print(f"页数: {doc.page_count}")
+    # pyrefly: ignore [missing-attribute]
     print(f"标题: {doc.metadata.get('title', 'N/A')}")
+    # pyrefly: ignore [missing-attribute]
     print(f"作者: {doc.metadata.get('author', 'N/A')}")
+    # pyrefly: ignore [missing-attribute]
     print(f"创建日期: {doc.metadata.get('creationDate', 'N/A')}")
+    # pyrefly: ignore [missing-attribute]
     print(f"修改日期: {doc.metadata.get('modDate', 'N/A')}")
     print(f"文件大小: {input_path.stat().st_size / 1024:.1f} KB")
     doc.close()
@@ -281,6 +286,7 @@ def pdf_ocr(input_path: Path, output_path: Path, lang: str = "chi_sim+eng") -> N
         new_page = new_doc.new_page(width=page.rect.width, height=page.rect.height)
         new_page.insert_image(new_page.rect, pixmap=pix)
         text_rect = fitz.Rect(0, 0, page.rect.width, page.rect.height)
+        # pyrefly: ignore [bad-argument-type]
         new_page.insert_textbox(text_rect, ocr_text)
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
@@ -319,6 +325,7 @@ def pdf_to_images(input_path: Path, output_dir: Path, dpi: int = 300) -> None:
     doc = fitz.open(str(input_path))
     output_dir.mkdir(parents=True, exist_ok=True)
 
+    # pyrefly: ignore [bad-argument-type]
     for page_num, page in enumerate(doc):
         pix = page.get_pixmap(dpi=dpi)
         image_path = output_dir / f"{input_path.stem}_page_{page_num + 1}.png"
@@ -436,87 +443,79 @@ def main() -> None:  # noqa: PLR0912
     args = parser.parse_args()
 
     if args.command == "m":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_merge", fn=pdf_merge, args=([Path(p) for p in args.inputs], Path(args.output)))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_merge", fn=pdf_merge, args=([Path(p) for p in args.inputs], Path(args.output)))
+        ])
     elif args.command == "s":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_split", fn=pdf_split, args=(Path(args.input), Path(args.output_dir)))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_split", fn=pdf_split, args=(Path(args.input), Path(args.output_dir)))
+        ])
     elif args.command == "c":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_compress", fn=pdf_compress, args=(Path(args.input), Path(args.output)))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_compress", fn=pdf_compress, args=(Path(args.input), Path(args.output)))
+        ])
     elif args.command == "e":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_encrypt", fn=pdf_encrypt, args=(Path(args.input), Path(args.output), args.password))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_encrypt", fn=pdf_encrypt, args=(Path(args.input), Path(args.output), args.password))
+        ])
     elif args.command == "d":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_decrypt", fn=pdf_decrypt, args=(Path(args.input), Path(args.output), args.password))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_decrypt", fn=pdf_decrypt, args=(Path(args.input), Path(args.output), args.password))
+        ])
     elif args.command == "xt":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_extract_text", fn=pdf_extract_text, args=(Path(args.input), Path(args.output)))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_extract_text", fn=pdf_extract_text, args=(Path(args.input), Path(args.output)))
+        ])
     elif args.command == "xi":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_extract_images", fn=pdf_extract_images, args=(Path(args.input), Path(args.output_dir)))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_extract_images", fn=pdf_extract_images, args=(Path(args.input), Path(args.output_dir)))
+        ])
     elif args.command == "w":
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "pdf_watermark",
-                    fn=pdf_add_watermark,
-                    args=(Path(args.input), Path(args.output)),
-                    kwargs={"text": args.text},
-                )
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "pdf_watermark",
+                fn=pdf_add_watermark,
+                args=(Path(args.input), Path(args.output)),
+                kwargs={"text": args.text},
+            )
+        ])
     elif args.command == "r":
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "pdf_rotate",
-                    fn=pdf_rotate,
-                    args=(Path(args.input), Path(args.output)),
-                    kwargs={"rotation": args.rotation},
-                )
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "pdf_rotate",
+                fn=pdf_rotate,
+                args=(Path(args.input), Path(args.output)),
+                kwargs={"rotation": args.rotation},
+            )
+        ])
     elif args.command == "crop":
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "pdf_crop",
-                    fn=pdf_crop,
-                    args=(Path(args.input), Path(args.output)),
-                    kwargs={"margins": (args.left, args.top, args.right, args.bottom)},
-                )
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "pdf_crop",
+                fn=pdf_crop,
+                args=(Path(args.input), Path(args.output)),
+                kwargs={"margins": (args.left, args.top, args.right, args.bottom)},
+            )
+        ])
     elif args.command == "i":
         graph = px.Graph.from_specs([px.TaskSpec("pdf_info", fn=pdf_info, args=(Path(args.input),))])
     elif args.command == "ocr":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_ocr", fn=pdf_ocr, args=(Path(args.input), Path(args.output)), kwargs={"lang": args.lang})]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_ocr", fn=pdf_ocr, args=(Path(args.input), Path(args.output)), kwargs={"lang": args.lang})
+        ])
     elif args.command == "img":
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "pdf_to_images",
-                    fn=pdf_to_images,
-                    args=(Path(args.input), Path(args.output_dir)),
-                    kwargs={"dpi": args.dpi},
-                )
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "pdf_to_images",
+                fn=pdf_to_images,
+                args=(Path(args.input), Path(args.output_dir)),
+                kwargs={"dpi": args.dpi},
+            )
+        ])
     elif args.command == "repair":
-        graph = px.Graph.from_specs(
-            [px.TaskSpec("pdf_repair", fn=pdf_repair, args=(Path(args.input), Path(args.output)))]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("pdf_repair", fn=pdf_repair, args=(Path(args.input), Path(args.output)))
+        ])
     else:
         parser.print_help()
         return

src/pyflowx/cli/which.py

@@ -6,46 +6,16 @@
 from __future__ import annotations
 
 import argparse
-import shutil
-from pathlib import Path
 
 import pyflowx as px
-
-
-def which_command(command: str) -> Path | None:
-    """查找命令路径.
-
-    Parameters
-    ----------
-    command : str
-        命令名称
-
-    Returns
-    -------
-    Path | None
-        命令路径, 如果未找到则返回 None
-    """
-    cmd_path = shutil.which(command)
-    if cmd_path:
-        print(f"匹配路径: - {cmd_path}")
-        return Path(cmd_path)
-    else:
-        print(f"{command}: 未找到")
-        return None
+from pyflowx.tasks.system import WHICH
 
 
 def main() -> None:
     """命令查找工具主函数."""
-    parser = argparse.ArgumentParser(
-        description="Which - 命令查找工具",
-        usage="which <command> [command ...]",
-    )
-    parser.add_argument(
-        "commands",
-        type=str,
-        nargs="+",
-        help="要查找的命令名称 (如: python pip node npm git uv rustc cargo)",
-    )
+    parser = argparse.ArgumentParser(description="Which - 命令查找工具")
+    parser.add_argument("commands", nargs="+", help="要查找的命令名称, 如: python ls ps gcc...")
     args = parser.parse_args()
-    graph = px.Graph.from_specs([px.TaskSpec(f"which_{cmd}", fn=which_command, args=(cmd,)) for cmd in args.commands])
+
+    graph = px.Graph.from_specs([WHICH(cmd) for cmd in args.commands])
     px.run(graph, strategy="thread")

src/pyflowx/examples/async_aggregation.py

@@ -31,14 +31,12 @@ def aggregate(ctx: px.Context) -> dict[str, Any]:
 
 
 def main() -> None:
-    graph = px.Graph.from_specs(
-        [
-            # Static positional args parameterise the same function twice.
-            px.TaskSpec("fetch_user", fetch_user, args=(1,)),
-            px.TaskSpec("fetch_posts", fetch_posts, args=(1,)),
-            px.TaskSpec("aggregate", aggregate, depends_on=("fetch_user", "fetch_posts")),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        # Static positional args parameterise the same function twice.
+        px.TaskSpec("fetch_user", fetch_user, args=(1,)),
+        px.TaskSpec("fetch_posts", fetch_posts, args=(1,)),
+        px.TaskSpec("aggregate", aggregate, depends_on=("fetch_user", "fetch_posts")),
+    ])
 
     print("=== Dry run ===")
     _ = px.run(graph, strategy="async", dry_run=True)

src/pyflowx/examples/etl_pipeline.py

@@ -10,19 +10,21 @@ Demonstrates the core PyFlowX workflow:
 
 from __future__ import annotations
 
+from typing import Any
+
 import pyflowx as px
 
 # --- task functions: pure, testable, no framework coupling ------------- #
 
 
-def extract_customers() -> list[dict]:
+def extract_customers() -> list[dict[str, Any]]:
     return [
         {"id": "C001", "name": "Alice"},
         {"id": "C002", "name": "Bob"},
     ]
 
 
-def extract_orders() -> list[dict]:
+def extract_orders() -> list[dict[str, Any]]:
     return [
         {"id": "O001", "customer_id": "C001", "amount": 150.0},
         {"id": "O002", "customer_id": "C002", "amount": 200.5},
@@ -31,32 +33,30 @@ def extract_orders() -> list[dict]:
 
 # Parameter names match dependency names → automatic injection.
 def transform(
-    extract_customers: list[dict],
-    extract_orders: list[dict],
-) -> list[dict]:
+    extract_customers: list[dict[str, Any]],
+    extract_orders: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
     cmap = {c["id"]: c for c in extract_customers}
     return [{**o, "customer_name": cmap[o["customer_id"]]["name"]} for o in extract_orders if o["customer_id"] in cmap]
 
 
-def load(transform: list[dict]) -> int:
+def load(transform: list[dict[str, Any]]) -> int:
     print(f"  loaded {len(transform)} records")
     return len(transform)
 
 
 def main() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("extract_customers", extract_customers, tags=("extract",)),
-            px.TaskSpec("extract_orders", extract_orders, tags=("extract",)),
-            px.TaskSpec(
-                "transform",
-                transform,
-                depends_on=("extract_customers", "extract_orders"),
-                tags=("transform",),
-            ),
-            px.TaskSpec("load", load, depends_on=("transform",), retries=1, tags=("load",)),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("extract_customers", extract_customers, tags=("extract",)),
+        px.TaskSpec("extract_orders", extract_orders, tags=("extract",)),
+        px.TaskSpec(
+            "transform",
+            transform,
+            depends_on=("extract_customers", "extract_orders"),
+            tags=("transform",),
+        ),
+        px.TaskSpec("load", load, depends_on=("transform",), retries=1, tags=("load",)),
+    ])
 
     print("=== Execution plan ===")
     print(graph.describe())

src/pyflowx/examples/parallel_run.py

@@ -29,13 +29,11 @@ def merge(fetch_a: str, fetch_b: str) -> str:
 
 
 def main() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("fetch_a", fetch_a),
-            px.TaskSpec("fetch_b", fetch_b),
-            px.TaskSpec("merge", merge, depends_on=("fetch_a", "fetch_b")),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("fetch_a", fetch_a),
+        px.TaskSpec("fetch_b", fetch_b),
+        px.TaskSpec("merge", merge, depends_on=("fetch_a", "fetch_b")),
+    ])
 
     print("=== Mermaid diagram ===")
     print(graph.to_mermaid("LR"))

src/pyflowx/executors.py

@@ -132,7 +132,9 @@ def _check_conditions_for_skip(
     if failed_conditions:
         return f"条件不满足: {', '.join(failed_conditions)}"
     elif spec.skip_if_missing and not spec._is_cmd_available():
-        return f"命令不存在: {spec.cmd[0] if spec.cmd else 'unknown'}"
+        # _is_cmd_available() 仅对 list[str] 类型返回 False
+        cmd_name = spec.cmd[0] if isinstance(spec.cmd, list) and spec.cmd else "unknown"
+        return f"命令不存在: {cmd_name}"
     else:
         return "条件不满足"
 

src/pyflowx/storage.py

@@ -17,10 +17,16 @@
 from __future__ import annotations
 
 import json
+import sys
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Any, Mapping
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 from .errors import StorageError
 
 
@@ -54,18 +60,23 @@ class MemoryBackend(StateBackend):
     def __init__(self) -> None:
         self._store: dict[str, Any] = {}
 
+    @override
     def load(self) -> Mapping[str, Any]:
         return dict(self._store)
 
+    @override
     def save(self, name: str, value: Any) -> None:
         self._store[name] = value
 
+    @override
     def has(self, name: str) -> bool:
         return name in self._store
 
+    @override
     def get(self, name: str) -> Any:
         return self._store[name]
 
+    @override
     def clear(self) -> None:
         self._store.clear()
 
@@ -104,9 +115,11 @@ class JSONBackend(StateBackend):
         except (OSError, TypeError) as exc:
             raise StorageError(f"cannot write state file {self._path!r}", exc) from exc
 
+    @override
     def load(self) -> Mapping[str, Any]:
         return dict(self._store)
 
+    @override
     def save(self, name: str, value: Any) -> None:
         # 在修改内存状态前先校验可序列化性。
         try:
@@ -116,12 +129,15 @@ class JSONBackend(StateBackend):
         self._store[name] = value
         self._flush()
 
+    @override
     def has(self, name: str) -> bool:
         return name in self._store
 
+    @override
     def get(self, name: str) -> Any:
         return self._store[name]
 
+    @override
     def clear(self) -> None:
         self._store.clear()
         self._flush()

src/pyflowx/task.py

@@ -15,6 +15,7 @@
 * ``TaskStatus`` 是封闭枚举；执行器绝不发明临时字符串。
 """
 
+import sys
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
@@ -28,12 +29,16 @@ from typing import (
     Mapping,
     Optional,
     Tuple,
-    TypeVar,
     Union,
     cast,
 )
 
-T = TypeVar("T")
+if sys.version_info >= (3, 13):
+    from typing import TypeVar
+else:
+    from typing_extensions import TypeVar
+
+T = TypeVar("T", default=Any)
 
 # 任务可调用对象可以是同步或异步的。显式保留联合类型，让 mypy 理解两种形态。
 TaskFn = Union[
@@ -174,19 +179,18 @@ class TaskSpec(Generic[T]):
         verbose = self.verbose
 
         if isinstance(cmd, list):
-            cmd_list = cast(List[str], cmd)
 
             def _run_list() -> T:
                 import subprocess
 
-                cmd_str = " ".join(str(arg) for arg in cmd_list)
+                cmd_str = " ".join(arg for arg in cmd)
                 if verbose:
                     print(f"[verbose] 执行命令: {cmd_str}", flush=True)
                     if cwd is not None:
                         print(f"[verbose] 工作目录: {cwd}", flush=True)
                 try:
                     result = subprocess.run(
-                        cmd_list,
+                        cmd,
                         cwd=cwd,
                         timeout=timeout,
                         capture_output=not verbose,
@@ -288,7 +292,7 @@ class TaskSpec(Generic[T]):
 
         cmd = self.cmd
         if isinstance(cmd, list) and cmd:
-            first_arg = cast(str, cmd[0])
+            first_arg = cmd[0]
             return shutil.which(first_arg) is not None
         return True
 

src/pyflowx/tasks/__init__.py

@@ -0,0 +1 @@
+

src/pyflowx/tasks/system.py

@@ -0,0 +1,51 @@
+"""系统操作任务模块.
+
+提供常用的系统操作任务封装, 包括清屏、环境变量设置、命令查找等.
+遵循实用主义原则, 仅提供核心功能, 无过度设计.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+import pyflowx as px
+from pyflowx.conditions import Constants
+
+
+def CLR():
+    """清屏任务."""
+    cmd = ["cls"] if Constants.IS_WINDOWS else ["clear"]
+    return px.TaskSpec("clear_screen", fn=lambda: subprocess.run(cmd, check=False))
+
+
+def SETENV(name: str, value: str, default: bool = False):
+    """设置环境变量任务."""
+
+    def set_env():
+        if default:
+            os.environ.setdefault(name, value)
+        else:
+            os.environ[name] = value
+
+    return px.TaskSpec(f"setenv_{name.lower()}", fn=set_env, verbose=True)
+
+
+def WHICH(cmd: str):
+    """查找命令路径任务."""
+    which_cmd = "where" if Constants.IS_WINDOWS else "which"
+
+    def find_command():
+        result = subprocess.run([which_cmd, cmd], capture_output=True, text=True, check=False)
+
+        if result.returncode == 0:
+            # Windows 的 where 可能返回多行, 取第一个
+            path = result.stdout.strip().split("\n")[0].strip()
+            print(f"{cmd} -> {path}")
+        else:
+            print(f"{cmd} -> 未找到")
+
+    return px.TaskSpec(f"which_{cmd}", fn=find_command)
+
+
+__all__ = ["CLR", "SETENV", "WHICH"]

tests/cli/test_bumpversion.py

@@ -7,6 +7,7 @@ from unittest.mock import patch
 
 import pytest
 
+import pyflowx as px
 from pyflowx.cli import bumpversion
 
 
@@ -76,7 +77,7 @@ class TestBumpFileVersion:
         content = test_file.read_text(encoding="utf-8")
         assert "build" not in content
 
-    def test_no_version_found(self, tmp_path: Path, capsys) -> None:
+    def test_no_version_found(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
         """Should return None when no version pattern found."""
         test_file = tmp_path / "test.txt"
         test_file.write_text("no version here", encoding="utf-8")
@@ -149,7 +150,7 @@ dependencies = ["lib >= 2.0.0", "other >= 3.0.0"]
         assert "lib >= 2.0.0" in updated
         assert "other >= 3.0.0" in updated
 
-    def test_file_read_error(self, tmp_path: Path, capsys) -> None:
+    def test_file_read_error(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
         """Should handle file read errors."""
         # 创建一个目录而不是文件
         test_file = tmp_path / "test_dir"
@@ -158,7 +159,7 @@ dependencies = ["lib >= 2.0.0", "other >= 3.0.0"]
         with pytest.raises(Exception):  # noqa: B017
             bumpversion.bump_file_version(test_file, "patch")
 
-    def test_file_write_error(self, tmp_path: Path, capsys) -> None:
+    def test_file_write_error(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
         """Should handle file write errors."""
         # 在只读目录中创建文件（这个测试在某些系统上可能不适用）
         test_file = tmp_path / "readonly.toml"
@@ -224,7 +225,7 @@ class TestVersionPattern:
 class TestEdgeCases:
     """Test edge cases and error handling."""
 
-    def test_empty_file(self, tmp_path: Path, capsys) -> None:
+    def test_empty_file(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
         """Should handle empty file."""
         test_file = tmp_path / "empty.txt"
         test_file.write_text("", encoding="utf-8")
@@ -280,7 +281,7 @@ class TestBumpVersionCli:
         # Mock px.run: 只真正执行第一次调用(版本更新),其余返回空 dict
         with patch("sys.argv", ["bumpversion", "minor", "--no-tag"]), patch("pyflowx.run") as mock_run:
 
-            def run_side_effect(graph, strategy=None):
+            def run_side_effect(graph: px.Graph, strategy: str | None = None):
                 # 执行实际版本更新任务
                 results = {}
                 for spec in graph.specs.values():
@@ -294,14 +295,14 @@ class TestBumpVersionCli:
         # 验证版本号已更新
         assert test_file.read_text(encoding="utf-8") == '__version__ = "1.1.0"'
 
-    def test_no_valid_files(self, tmp_path: Path, capsys) -> None:
+    def test_no_valid_files(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
         """Should handle no valid files."""
         test_file = tmp_path / "test.txt"
         test_file.write_text("这是一个测试文件", encoding="utf-8")
 
         with patch("sys.argv", ["bumpversion", "minor", "--no-tag"]), patch("pyflowx.run") as mock_run:
 
-            def run_side_effect(graph, strategy=None):
+            def run_side_effect(graph: px.Graph, strategy: str | None = None):
                 # 执行实际版本更新任务
                 results = {}
                 for spec in graph.specs.values():

tests/cli/test_clearscreen.py

@@ -2,33 +2,10 @@
 
 from __future__ import annotations
 
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
 import pyflowx as px
 from pyflowx.cli import clearscreen
-from pyflowx.conditions import Constants
-
-
-# ---------------------------------------------------------------------- #
-# clear_screen
-# ---------------------------------------------------------------------- #
-class TestClearScreen:
-    """Test clear_screen function."""
-
-    def test_clear_screen_windows(self) -> None:
-        """Should clear screen on Windows."""
-        if Constants.IS_WINDOWS:
-            with patch("subprocess.run") as mock_run:
-                mock_run.return_value = MagicMock(returncode=0)
-                clearscreen.clear_screen()
-                assert mock_run.called
-
-    def test_clear_screen_linux(self) -> None:
-        """Should clear screen on Linux."""
-        with patch.object(Constants, "IS_WINDOWS", False), patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(returncode=0)
-            clearscreen.clear_screen()
-            assert mock_run.called
 
 
 # ---------------------------------------------------------------------- #

tests/cli/test_emlmanager.py

@@ -30,6 +30,8 @@ class TestEmailDatabase:
         db_path = tmp_path / "test.db"
         db = emlmanager.EmailDatabase(db_path)
 
+        assert db.conn is not None
+
         cursor = db.conn.cursor()
         cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='emails'")
         result = cursor.fetchone()
@@ -41,6 +43,8 @@ class TestEmailDatabase:
         db_path = tmp_path / "test.db"
         db = emlmanager.EmailDatabase(db_path)
 
+        assert db.conn is not None
+
         cursor = db.conn.cursor()
         cursor.execute("SELECT name FROM sqlite_master WHERE type='index' AND name='idx_subject'")
         result = cursor.fetchone()
@@ -68,6 +72,7 @@ class TestEmailDatabase:
 
         result = db.insert_email(email_data)
         assert result is True
+        assert db.conn is not None
 
         cursor = db.conn.cursor()
         cursor.execute("SELECT COUNT(*) FROM emails")
@@ -101,6 +106,8 @@ class TestEmailDatabase:
         email_data["file_hash"] = "xyz789"
         db.insert_email(email_data)
 
+        assert db.conn is not None
+
         cursor = db.conn.cursor()
         cursor.execute("SELECT COUNT(*) FROM emails")
         count = cursor.fetchone()[0]
@@ -118,21 +125,19 @@ class TestEmailDatabase:
 
         # Insert test emails
         for i in range(5):
-            db.insert_email(
-                {
-                    "file_path": f"/test/path{i}.eml",
-                    "file_hash": f"hash{i}",
-                    "subject": f"Subject {i}",
-                    "sender": f"sender{i}@example.com",
-                    "recipients": "recipient@example.com",
-                    "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
-                    "date_parsed": f"2024-01-0{i + 1}T12:00:00",
-                    "body_text": f"Body {i}",
-                    "body_html": f"<p>Body {i}</p>",
-                    "has_attachments": 0,
-                    "file_size": 1024,
-                }
-            )
+            db.insert_email({
+                "file_path": f"/test/path{i}.eml",
+                "file_hash": f"hash{i}",
+                "subject": f"Subject {i}",
+                "sender": f"sender{i}@example.com",
+                "recipients": "recipient@example.com",
+                "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
+                "date_parsed": f"2024-01-0{i + 1}T12:00:00",
+                "body_text": f"Body {i}",
+                "body_html": f"<p>Body {i}</p>",
+                "has_attachments": 0,
+                "file_size": 1024,
+            })
 
         results = db.search_emails(limit=3)
         assert len(results) == 3
@@ -143,37 +148,33 @@ class TestEmailDatabase:
         db_path = tmp_path / "test.db"
         db = emlmanager.EmailDatabase(db_path)
 
-        db.insert_email(
-            {
-                "file_path": "/test/path1.eml",
-                "file_hash": "hash1",
-                "subject": "Important Meeting",
-                "sender": "sender1@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Mon, 1 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-01T12:00:00",
-                "body_text": "Meeting body",
-                "body_html": "<p>Meeting body</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path1.eml",
+            "file_hash": "hash1",
+            "subject": "Important Meeting",
+            "sender": "sender1@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Mon, 1 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-01T12:00:00",
+            "body_text": "Meeting body",
+            "body_html": "<p>Meeting body</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
-        db.insert_email(
-            {
-                "file_path": "/test/path2.eml",
-                "file_hash": "hash2",
-                "subject": "Casual Chat",
-                "sender": "sender2@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Tue, 2 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-02T12:00:00",
-                "body_text": "Chat body",
-                "body_html": "<p>Chat body</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path2.eml",
+            "file_hash": "hash2",
+            "subject": "Casual Chat",
+            "sender": "sender2@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Tue, 2 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-02T12:00:00",
+            "body_text": "Chat body",
+            "body_html": "<p>Chat body</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
         results = db.search_emails(keyword="Meeting", field="subject")
         assert len(results) == 1
@@ -185,37 +186,33 @@ class TestEmailDatabase:
         db_path = tmp_path / "test.db"
         db = emlmanager.EmailDatabase(db_path)
 
-        db.insert_email(
-            {
-                "file_path": "/test/path1.eml",
-                "file_hash": "hash1",
-                "subject": "Test",
-                "sender": "alice@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Mon, 1 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-01T12:00:00",
-                "body_text": "Body",
-                "body_html": "<p>Body</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path1.eml",
+            "file_hash": "hash1",
+            "subject": "Test",
+            "sender": "alice@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Mon, 1 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-01T12:00:00",
+            "body_text": "Body",
+            "body_html": "<p>Body</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
-        db.insert_email(
-            {
-                "file_path": "/test/path2.eml",
-                "file_hash": "hash2",
-                "subject": "Test",
-                "sender": "bob@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Tue, 2 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-02T12:00:00",
-                "body_text": "Body",
-                "body_html": "<p>Body</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path2.eml",
+            "file_hash": "hash2",
+            "subject": "Test",
+            "sender": "bob@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Tue, 2 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-02T12:00:00",
+            "body_text": "Body",
+            "body_html": "<p>Body</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
         results = db.search_emails(keyword="alice", field="sender")
         assert len(results) == 1
@@ -227,21 +224,19 @@ class TestEmailDatabase:
         db_path = tmp_path / "test.db"
         db = emlmanager.EmailDatabase(db_path)
 
-        db.insert_email(
-            {
-                "file_path": "/test/path1.eml",
-                "file_hash": "hash1",
-                "subject": "Project Update",
-                "sender": "manager@example.com",
-                "recipients": "team@example.com",
-                "date": "Mon, 1 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-01T12:00:00",
-                "body_text": "Please review the quarterly report",
-                "body_html": "<p>Please review the quarterly report</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path1.eml",
+            "file_hash": "hash1",
+            "subject": "Project Update",
+            "sender": "manager@example.com",
+            "recipients": "team@example.com",
+            "date": "Mon, 1 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-01T12:00:00",
+            "body_text": "Please review the quarterly report",
+            "body_html": "<p>Please review the quarterly report</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
         # Search for keyword in subject
         results = db.search_emails(keyword="Project", field="all")
@@ -258,53 +253,47 @@ class TestEmailDatabase:
         db = emlmanager.EmailDatabase(db_path)
 
         # Insert emails with same subject (different prefixes)
-        db.insert_email(
-            {
-                "file_path": "/test/path1.eml",
-                "file_hash": "hash1",
-                "subject": "Meeting Tomorrow",
-                "sender": "sender1@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Mon, 1 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-01T12:00:00",
-                "body_text": "Body 1",
-                "body_html": "<p>Body 1</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path1.eml",
+            "file_hash": "hash1",
+            "subject": "Meeting Tomorrow",
+            "sender": "sender1@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Mon, 1 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-01T12:00:00",
+            "body_text": "Body 1",
+            "body_html": "<p>Body 1</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
-        db.insert_email(
-            {
-                "file_path": "/test/path2.eml",
-                "file_hash": "hash2",
-                "subject": "Re: Meeting Tomorrow",
-                "sender": "sender2@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Tue, 2 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-02T12:00:00",
-                "body_text": "Body 2",
-                "body_html": "<p>Body 2</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path2.eml",
+            "file_hash": "hash2",
+            "subject": "Re: Meeting Tomorrow",
+            "sender": "sender2@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Tue, 2 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-02T12:00:00",
+            "body_text": "Body 2",
+            "body_html": "<p>Body 2</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
-        db.insert_email(
-            {
-                "file_path": "/test/path3.eml",
-                "file_hash": "hash3",
-                "subject": "Different Topic",
-                "sender": "sender3@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Wed, 3 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-03T12:00:00",
-                "body_text": "Body 3",
-                "body_html": "<p>Body 3</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path3.eml",
+            "file_hash": "hash3",
+            "subject": "Different Topic",
+            "sender": "sender3@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Wed, 3 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-03T12:00:00",
+            "body_text": "Body 3",
+            "body_html": "<p>Body 3</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
         grouped = db.get_grouped_emails()
         # Should have 2 groups: "Meeting Tomorrow" and "Different Topic"
@@ -333,21 +322,19 @@ class TestEmailDatabase:
         assert db.get_email_count() == 0
 
         for i in range(3):
-            db.insert_email(
-                {
-                    "file_path": f"/test/path{i}.eml",
-                    "file_hash": f"hash{i}",
-                    "subject": f"Subject {i}",
-                    "sender": f"sender{i}@example.com",
-                    "recipients": "recipient@example.com",
-                    "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
-                    "date_parsed": f"2024-01-0{i + 1}T12:00:00",
-                    "body_text": f"Body {i}",
-                    "body_html": f"<p>Body {i}</p>",
-                    "has_attachments": 0,
-                    "file_size": 1024,
-                }
-            )
+            db.insert_email({
+                "file_path": f"/test/path{i}.eml",
+                "file_hash": f"hash{i}",
+                "subject": f"Subject {i}",
+                "sender": f"sender{i}@example.com",
+                "recipients": "recipient@example.com",
+                "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
+                "date_parsed": f"2024-01-0{i + 1}T12:00:00",
+                "body_text": f"Body {i}",
+                "body_html": f"<p>Body {i}</p>",
+                "has_attachments": 0,
+                "file_size": 1024,
+            })
 
         assert db.get_email_count() == 3
         db.close()
@@ -359,21 +346,19 @@ class TestEmailDatabase:
 
         # Insert some emails
         for i in range(3):
-            db.insert_email(
-                {
-                    "file_path": f"/test/path{i}.eml",
-                    "file_hash": f"hash{i}",
-                    "subject": f"Subject {i}",
-                    "sender": f"sender{i}@example.com",
-                    "recipients": "recipient@example.com",
-                    "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
-                    "date_parsed": f"2024-01-0{i + 1}T12:00:00",
-                    "body_text": f"Body {i}",
-                    "body_html": f"<p>Body {i}</p>",
-                    "has_attachments": 0,
-                    "file_size": 1024,
-                }
-            )
+            db.insert_email({
+                "file_path": f"/test/path{i}.eml",
+                "file_hash": f"hash{i}",
+                "subject": f"Subject {i}",
+                "sender": f"sender{i}@example.com",
+                "recipients": "recipient@example.com",
+                "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
+                "date_parsed": f"2024-01-0{i + 1}T12:00:00",
+                "body_text": f"Body {i}",
+                "body_html": f"<p>Body {i}</p>",
+                "has_attachments": 0,
+                "file_size": 1024,
+            })
 
         assert db.get_email_count() == 3
 
@@ -411,7 +396,7 @@ class TestDecodeMimeWords:
 
     def test_decode_none(self) -> None:
         """Should handle None input."""
-        result = emlmanager.decode_mime_words(None)
+        result = emlmanager.decode_mime_words("")
         assert result == ""
 
     def test_decode_mixed_encoding(self) -> None:
@@ -702,21 +687,19 @@ class TestEmlManagerHandler:
 
         # Insert some emails
         for i in range(3):
-            db.insert_email(
-                {
-                    "file_path": f"/test/path{i}.eml",
-                    "file_hash": f"hash{i}",
-                    "subject": f"Subject {i}",
-                    "sender": f"sender{i}@example.com",
-                    "recipients": "recipient@example.com",
-                    "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
-                    "date_parsed": f"2024-01-0{i + 1}T12:00:00",
-                    "body_text": f"Body {i}",
-                    "body_html": f"<p>Body {i}</p>",
-                    "has_attachments": 0,
-                    "file_size": 1024,
-                }
-            )
+            db.insert_email({
+                "file_path": f"/test/path{i}.eml",
+                "file_hash": f"hash{i}",
+                "subject": f"Subject {i}",
+                "sender": f"sender{i}@example.com",
+                "recipients": "recipient@example.com",
+                "date": f"Mon, {i + 1} Jan 2024 12:00:00 +0000",
+                "date_parsed": f"2024-01-0{i + 1}T12:00:00",
+                "body_text": f"Body {i}",
+                "body_html": f"<p>Body {i}</p>",
+                "has_attachments": 0,
+                "file_size": 1024,
+            })
 
         # Create a mock handler instance without calling __init__
         handler = Mock(spec=emlmanager.EmlManagerHandler)
@@ -738,21 +721,19 @@ class TestEmlManagerHandler:
         db = emlmanager.EmailDatabase(db_path)
 
         # Insert test email
-        db.insert_email(
-            {
-                "file_path": "/test/path.eml",
-                "file_hash": "hash",
-                "subject": "Test Subject",
-                "sender": "sender@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Mon, 1 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-01T12:00:00",
-                "body_text": "Test body",
-                "body_html": "<p>Test body</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path.eml",
+            "file_hash": "hash",
+            "subject": "Test Subject",
+            "sender": "sender@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Mon, 1 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-01T12:00:00",
+            "body_text": "Test body",
+            "body_html": "<p>Test body</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
         # Create a mock handler instance without calling __init__
         handler = Mock(spec=emlmanager.EmlManagerHandler)
@@ -775,21 +756,19 @@ class TestEmlManagerHandler:
         db = emlmanager.EmailDatabase(db_path)
 
         # Insert test email
-        db.insert_email(
-            {
-                "file_path": "/test/path.eml",
-                "file_hash": "hash",
-                "subject": "Test Subject",
-                "sender": "sender@example.com",
-                "recipients": "recipient@example.com",
-                "date": "Mon, 1 Jan 2024 12:00:00 +0000",
-                "date_parsed": "2024-01-01T12:00:00",
-                "body_text": "Test body",
-                "body_html": "<p>Test body</p>",
-                "has_attachments": 0,
-                "file_size": 1024,
-            }
-        )
+        db.insert_email({
+            "file_path": "/test/path.eml",
+            "file_hash": "hash",
+            "subject": "Test Subject",
+            "sender": "sender@example.com",
+            "recipients": "recipient@example.com",
+            "date": "Mon, 1 Jan 2024 12:00:00 +0000",
+            "date_parsed": "2024-01-01T12:00:00",
+            "body_text": "Test body",
+            "body_html": "<p>Test body</p>",
+            "has_attachments": 0,
+            "file_size": 1024,
+        })
 
         assert db.get_email_count() == 1
 

tests/cli/test_envrs.py

@@ -48,6 +48,7 @@ class TestSetRustMirror:
     def test_set_rust_mirror_unknown_uses_default(self, tmp_path: Path) -> None:
         """Should use default mirror for unknown mirror name."""
         with patch.object(Path, "home", return_value=tmp_path):
+            # pyrefly: ignore [bad-argument-type]
             envrs.set_rust_mirror("unknown")
             # Should use default mirror (tsinghua)
             assert os.environ.get("RUSTUP_DIST_SERVER") == "https://mirrors.tuna.tsinghua.edu.cn/rustup"

tests/cli/test_gittool.py

@@ -107,6 +107,7 @@ class TestTaskSpecDefinitions:
     def test_kill_tgit_spec(self) -> None:
         """kill_tgit spec should be properly defined."""
         assert gittool.kill_tgit.name == "task_kill"
+        assert isinstance(gittool.kill_tgit.cmd, list)
         assert "taskkill" in gittool.kill_tgit.cmd
 
 

tests/cli/test_pdftool.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -71,7 +72,7 @@ class TestPdfCompress:
             mock_fitz_open.return_value = mock_doc
 
             # Mock save to actually create the file
-            def mock_save(*args, **kwargs):
+            def mock_save(*args: Any, **kwargs: Any):
                 output_file.write_bytes(b"Compressed PDF")
 
             mock_doc.save = mock_save

tests/cli/test_which.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import shutil
-from pathlib import Path
 from unittest.mock import patch
 
 import pytest
@@ -12,45 +11,6 @@ import pyflowx as px
 from pyflowx.cli import which
 
 
-# ---------------------------------------------------------------------- #
-# which_command
-# ---------------------------------------------------------------------- #
-class TestWhichCommand:
-    """Test which_command function."""
-
-    def test_returns_path_when_command_found(self, capsys: pytest.CaptureFixture[str]) -> None:
-        """Should return Path when command is found."""
-        with patch.object(shutil, "which", return_value="/usr/bin/python"):
-            result = which.which_command("python")
-            assert result == Path("/usr/bin/python")
-            captured = capsys.readouterr()
-            assert "匹配路径" in captured.out
-            assert "/usr/bin/python" in captured.out
-
-    def test_returns_none_when_command_not_found(self, capsys: pytest.CaptureFixture[str]) -> None:
-        """Should return None when command is not found."""
-        with patch.object(shutil, "which", return_value=None):
-            result = which.which_command("nonexistent_cmd")
-            assert result is None
-            captured = capsys.readouterr()
-            assert "未找到" in captured.out
-            assert "nonexistent_cmd" in captured.out
-
-    def test_prints_match_path_on_success(self, capsys: pytest.CaptureFixture[str]) -> None:
-        """Should print '匹配路径: - <path>' on success."""
-        with patch.object(shutil, "which", return_value="C:\\Python\\python.exe"):
-            _ = which.which_command("python")
-            captured = capsys.readouterr()
-            assert "匹配路径: - C:\\Python\\python.exe" in captured.out
-
-    def test_prints_not_found_on_failure(self, capsys: pytest.CaptureFixture[str]) -> None:
-        """Should print '<command>: 未找到' on failure."""
-        with patch.object(shutil, "which", return_value=None):
-            _ = which.which_command("missing")
-            captured = capsys.readouterr()
-            assert "missing: 未找到" in captured.out
-
-
 # ---------------------------------------------------------------------- #
 # main function
 # ---------------------------------------------------------------------- #

tests/test_executors_edge_cases.py

@@ -54,7 +54,7 @@ def test_verbose_event_callback_running():
     assert report.success
 
 
-def test_verbose_run_with_success_lifecycle(capsys):
+def test_verbose_run_with_success_lifecycle(capsys: pytest.CaptureFixture[str]):
     """Test px.run with verbose=True prints SUCCESS lifecycle."""
     spec = px.TaskSpec("test", fn=lambda: "result")
     graph = px.Graph.from_specs([spec])
@@ -64,7 +64,7 @@ def test_verbose_run_with_success_lifecycle(capsys):
     assert "成功" in captured.out
 
 
-def test_verbose_run_with_failed_lifecycle(capsys):
+def test_verbose_run_with_failed_lifecycle(capsys: pytest.CaptureFixture[str]):
     """Test px.run with verbose=True prints FAILED lifecycle with error."""
 
     def raise_error():
@@ -80,7 +80,7 @@ def test_verbose_run_with_failed_lifecycle(capsys):
     assert "test error" in captured.out
 
 
-def test_verbose_run_with_skipped_lifecycle(capsys):
+def test_verbose_run_with_skipped_lifecycle(capsys: pytest.CaptureFixture[str]):
     """Test px.run with verbose=True prints SKIPPED lifecycle."""
     spec = px.TaskSpec(
         "test",
@@ -98,7 +98,7 @@ def test_verbose_run_with_user_callback():
     """Test px.run with verbose=True and user callback both called."""
     events = []
 
-    def on_event(event):
+    def on_event(event: px.TaskEvent):
         events.append(event)
 
     spec = px.TaskSpec("test", fn=lambda: "result")

tests/test_task_edge_cases.py

@@ -177,7 +177,7 @@ def test_taskspec_shell_cmd_file_not_found_mocked():
         _ = wrapped_fn()
 
 
-def test_taskspec_shell_cmd_with_cwd_verbose(capsys):
+def test_taskspec_shell_cmd_with_cwd_verbose(capsys: pytest.CaptureFixture[str]):
     """Test TaskSpec._wrap_cmd with shell command, cwd and verbose=True."""
     with tempfile.TemporaryDirectory() as tmpdir:
         if sys.platform == "win32":

typings/graphlib/graphlib.pyi

@@ -11,7 +11,7 @@ _NODE_DONE = ...
 class _NodeInfo:
     __slots__: list[str]
 
-    def __init__(self, node) -> None: ...
+    def __init__(self, node: Any) -> None: ...
 
 class CycleError(ValueError):
     """Subclass of ValueError raised by TopologicalSorterif cycles exist in the graph
@@ -29,8 +29,8 @@ class CycleError(ValueError):
 class TopologicalSorter:
     """Provides functionality to topologically sort a graph of hashable nodes"""
 
-    def __init__(self, graph=...) -> None: ...
-    def add(self, node, *predecessors) -> None:
+    def __init__(self, graph: Any) -> None: ...
+    def add(self, node: Any, *predecessors: Any) -> None:
         """Add a new node and its predecessors to the graph.
 
         Both the *node* and all elements in *predecessors* must be hashable.
@@ -86,7 +86,7 @@ class TopologicalSorter:
         ...
 
     def __bool__(self) -> bool: ...
-    def done(self, *nodes) -> None:
+    def done(self, *nodes: Any) -> None:
         """Marks a set of nodes returned by "get_ready" as processed.
 
         This method unblocks any successor of each node in *nodes* for being returned

uv.lock

@@ -2184,10 +2184,12 @@ wheels = [
 
 [[package]]
 name = "pyflowx"
-version = "0.2.2"
+version = "0.2.5"
 source = { editable = "." }
 dependencies = [
     { name = "graphlib-backport", marker = "python_full_version < '3.9'" },
+    { name = "typing-extensions", version = "4.13.2", source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }, marker = "python_full_version < '3.9'" },
+    { name = "typing-extensions", version = "4.15.0", source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }, marker = "python_full_version >= '3.9'" },
 ]
 
 [package.optional-dependencies]
@@ -2257,6 +2259,7 @@ requires-dist = [
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8.0" },
     { name = "tox", marker = "extra == 'dev'", specifier = ">=4.25.0" },
     { name = "tox-uv", marker = "extra == 'dev'", specifier = ">=1.13.1" },
+    { name = "typing-extensions", specifier = ">=4.13.2" },
 ]
 provides-extras = ["dev", "office"]
 
@@ -3179,6 +3182,7 @@ name = "typing-extensions"
 version = "4.15.0"
 source = { registry = "https://mirrors.aliyun.com/pypi/simple/" }
 resolution-markers = [
+    "python_full_version >= '3.15'",
     "python_full_version >= '3.10' and python_full_version < '3.15'",
     "python_full_version > '3.9' and python_full_version < '3.10'",
     "python_full_version == '3.9'",