refactor(types): preserve retry and timing decorator contracts

app/runtime/execution.py

@@ -7,7 +7,7 @@ from concurrent.futures import Executor, Future, ThreadPoolExecutor, wait
 from contextlib import contextmanager
 from contextvars import Context, copy_context
 from functools import partial, wraps
-from typing import Any, Callable, TypeVar, cast
+from typing import Any, Awaitable, Callable, ParamSpec, TypeVar, cast
 
 from anyio.to_thread import run_sync
 
@@ -16,6 +16,8 @@ from app.schemas.exception import ImmediateException
 
 TaskResult = TypeVar("TaskResult")
 ExecutorResult = TypeVar("ExecutorResult")
+_Params = ParamSpec("_Params")
+_Result = TypeVar("_Result")
 
 # 包目录替换在线程池中执行，导入在同步生命周期线程中执行；两者须共享进程锁。
 _plugin_package_locks: dict[str, Any] = {}
@@ -46,6 +48,7 @@ def submit_with_context(
     context = copy_context()
 
     def submit() -> Future[ExecutorResult]:
+        """在无继承上下文中提交，再由 worker 执行已捕获的调用方快照。"""
         return executor.submit(context.run, func, *args, **kwargs)
 
     return Context().run(submit)
@@ -224,8 +227,13 @@ async def run_in_threadpool_to_completion(
     return result
 
 
-def retry(ExceptionToCheck: Any,
-          tries: int = 3, delay: int = 3, backoff: int = 2, logger: Any = None):
+def retry(
+    ExceptionToCheck: type[BaseException] | tuple[type[BaseException], ...],
+    tries: int = 3,
+    delay: int = 3,
+    backoff: int = 2,
+    logger: Any = None,
+) -> Callable[[Callable[_Params, _Result]], Callable[_Params, _Result]]:
     """
     :param ExceptionToCheck: 需要捕获的异常
     :param tries: 重试次数
@@ -234,8 +242,10 @@ def retry(ExceptionToCheck: Any,
     :param logger: 日志对象
     """
 
-    def deco_retry(f):
-        def f_retry(*args, **kwargs):
+    def deco_retry(f: Callable[_Params, _Result]) -> Callable[_Params, _Result]:
+        """保留调用参数与返回类型，按原有检测方式选择同步或异步重试。"""
+        def f_retry(*args: _Params.args, **kwargs: _Params.kwargs) -> _Result:
+            """按既有退避间隔重试可捕获异常，立即终止异常直接交给调用方。"""
             mtries, mdelay = tries, delay
             while mtries > 1:
                 try:
@@ -253,11 +263,12 @@ def retry(ExceptionToCheck: Any,
                     mdelay *= backoff
             return f(*args, **kwargs)
 
-        async def async_f_retry(*args, **kwargs):
+        async def async_f_retry(*args: _Params.args, **kwargs: _Params.kwargs) -> object:
+            """仅在原函数被识别为协程时调用，异步等待与同步分支相同的重试策略。"""
             mtries, mdelay = tries, delay
             while mtries > 1:
                 try:
-                    return await f(*args, **kwargs)
+                    return await cast(Awaitable[object], f(*args, **kwargs))
                 except ImmediateException:
                     raise
                 except ExceptionToCheck as e:
@@ -269,26 +280,31 @@ def retry(ExceptionToCheck: Any,
                     await asyncio.sleep(mdelay)
                     mtries -= 1
                     mdelay *= backoff
-            return await f(*args, **kwargs)
+            return await cast(Awaitable[object], f(*args, **kwargs))
 
         # 根据函数类型返回相应的包装器
         if inspect.iscoroutinefunction(f):
-            return async_f_retry
+            # 仅协程分支可调用异步包装器，原 await 结果与参数原样透传。
+            return cast(Callable[_Params, _Result], async_f_retry)
         else:
             return f_retry
 
     return deco_retry
 
 
-def log_execution_time(logger: Any = None):
+def log_execution_time(
+    logger: Any = None,
+) -> Callable[[Callable[_Params, _Result]], Callable[_Params, _Result]]:
     """
     记录函数执行时间的装饰器
     :param logger: 日志记录器对象，用于记录异常信息
     """
 
-    def decorator(func: Callable):
+    def decorator(func: Callable[_Params, _Result]) -> Callable[_Params, _Result]:
+        """保留原函数元数据及调用合同，按原分派方式记录执行耗时。"""
         @wraps(func)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args: _Params.args, **kwargs: _Params.kwargs) -> _Result:
+            """同步函数成功后记录耗时，结果和异常沿用原传播路径。"""
             start_time = time.time()
             result = func(*args, **kwargs)
             end_time = time.time()
@@ -300,9 +316,10 @@ def log_execution_time(logger: Any = None):
             return result
 
         @wraps(func)
-        async def async_wrapper(*args, **kwargs):
+        async def async_wrapper(*args: _Params.args, **kwargs: _Params.kwargs) -> object:
+            """协程成功结束后记录耗时，异常不产生成功耗时日志。"""
             start_time = time.time()
-            result = await func(*args, **kwargs)
+            result = await cast(Awaitable[object], func(*args, **kwargs))
             end_time = time.time()
             msg = f"{func.__name__} execution time: {end_time - start_time:.2f} seconds"
             if logger:
@@ -313,7 +330,8 @@ def log_execution_time(logger: Any = None):
 
         # 根据函数类型返回相应的包装器
         if inspect.iscoroutinefunction(func):
-            return async_wrapper
+            # 已确认原函数返回协程，异步包装器保留同一 await 结果。
+            return cast(Callable[_Params, _Result], async_wrapper)
         else:
             return wrapper
 

docs/code-quality.md

@@ -75,7 +75,7 @@ uv run --locked --no-sync python scripts/architecture/complexity.py
 回调和返回值类型；全仓错误计数为零并不保证单独纳入 strict frontier 后也为零。
 
 2026-10-16 开始逐文件清理类型债务，`app/domain/title.py` 通过局部可空类型声明保留
-既有搜索解析行为，并纳入严格清单；当前清单共 74 个文件（73 个生产文件和 1 个脚本）。
+既有搜索解析行为，并纳入严格清单；当前清单共 75 个文件（74 个生产文件和 1 个脚本）。
 每个治理提交聚焦一个生产文件及其必要测试、门禁配置、真实下降基线和指标文档。
 验收同时检查完整严格清单与全宿主 Linux 分析，避免 `follow_imports = skip` 隐藏依赖
 签名冲突；不通过忽略诊断或放宽类型合同接受回退。最新文件清单以 `mypy.ini` 为准，

docs/refactor/optimization-checklist.md

@@ -106,9 +106,9 @@ ARCH-201 至 ARCH-204 均达到实现、验证、提交、推送和远端门禁
 | Model/Oper 事务债务 | 0 | 自建 Session、自动事务装饰器、直接 commit/rollback 等基线均为零 |
 | Module Contract | 215 specs / 211 methods / 263 calls | 动态方法名为 0；分类事实富化通过显式合同进入插件调度，旧 YAML 分类方法已移除；download 新增 custom_words 可选参数，旧 provider 签名通过显式合同兼容 |
 | Event Contract | 53 | 均已有 payload model，但当前全部是 diagnostic enforcement |
-| Python 源码量 | 372,158 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 |
+| Python 源码量 | 372,176 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 |
 | 长方法 | 309 个超过 80 行 | 本次 AST 扫描排除 `app/plugins/**`；61 个超过 150 行，17 个超过 250 行；新增函数仍受 C901/嵌套深度门禁约束 |
-| 全量 mypy 历史债务 | 8,997 / 478 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项；Transmission 进度回退值归一化再减少 2 项，逐文件逐错误码无增长 |
+| 全量 mypy 历史债务 | 8,943 / 477 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项；Transmission 进度回退值归一化再减少 2 项，逐文件逐错误码无增长 |
 | Ruff 历史诊断 | 100 | 低水位门禁通过，但规则集只覆盖 `E4/E7/E9/F/I` |
 | 覆盖率固定基线 | Application 80.00%，Domain 80.00% | Chain、Runtime、Agent、Adapter、Startup 未进入包级覆盖率门禁 |
 

mypy.ini

@@ -28,6 +28,7 @@ files =
     app/agent/contracts.py,
     app/runtime/correlation.py,
     app/runtime/coalesce.py,
+    app/runtime/execution.py,
     app/runtime/log.py,
     app/runtime/gc.py,
     app/runtime/localization.py,

tests/fixtures/architecture/mypy-baseline.json

@@ -837,7 +837,7 @@
     "type-arg": 2
   },
   "app/chain/recommend.py": {
-    "misc": 60,
+    "misc": 30,
     "no-untyped-call": 1,
     "no-untyped-def": 1,
     "type-arg": 31
@@ -1367,7 +1367,6 @@
     "arg-type": 1,
     "assignment": 27,
     "empty-body": 1,
-    "misc": 2,
     "no-any-return": 1,
     "no-untyped-call": 3,
     "no-untyped-def": 7,
@@ -1974,7 +1973,6 @@
   "app/modules/telegram/telegram.py": {
     "arg-type": 1,
     "assignment": 2,
-    "misc": 4,
     "no-any-return": 8,
     "no-untyped-call": 1,
     "no-untyped-def": 13,
@@ -2235,8 +2233,6 @@
     "union-attr": 1
   },
   "app/modules/vocechat/vocechat.py": {
-    "misc": 1,
-    "no-any-return": 3,
     "no-untyped-call": 1,
     "no-untyped-def": 3
   },
@@ -2262,8 +2258,7 @@
   "app/modules/wechat/wechat.py": {
     "arg-type": 1,
     "assignment": 9,
-    "misc": 1,
-    "no-any-return": 6,
+    "no-any-return": 2,
     "no-untyped-def": 5,
     "type-arg": 2,
     "union-attr": 1,
@@ -2387,10 +2382,6 @@
     "no-untyped-def": 16,
     "type-arg": 22
   },
-  "app/runtime/execution.py": {
-    "no-untyped-def": 8,
-    "type-arg": 1
-  },
   "app/runtime/extensions/module/adapter.py": {
     "arg-type": 1,
     "union-attr": 1,

tests/test_runtime_execution.py

@@ -122,6 +122,7 @@ async def test_threadpool_capacity_is_held_until_cancelled_call_finishes() -> No
     second_started = threading.Event()
 
     def blocking_call(started: threading.Event) -> None:
+        """占住线程容量直到测试放行，模拟取消后仍在运行的同步任务。"""
         started.set()
         release.wait()
 
@@ -171,6 +172,7 @@ async def test_cancelled_threadpool_call_preserves_worker_failure_as_cause() ->
     started = threading.Event()
 
     def failing_call() -> None:
+        """在线程收到放行后抛错，用于核对取消异常保留真实失败原因。"""
         started.set()
         release.wait()
         raise ValueError("worker failed")