refactor(types): govern reflection helpers without changing runtime signatures

app/foundation/reflection.py

@@ -8,11 +8,19 @@ import threading
 import tokenize
 import weakref
 from pathlib import Path
-from types import CodeType, FunctionType
-from typing import Any, Callable, List, Optional, get_type_hints
+from types import CodeType, FunctionType, ModuleType
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, get_type_hints
 
 FilterFuncType = Callable[[str, Any], bool]
 
+# 静态分析覆盖实际接收的可调用对象；运行时保留原注解供签名自省使用。
+if TYPE_CHECKING:
+    _ArgumentCallable = Callable[..., object]
+    _SignatureCallable = Callable[..., object]
+else:
+    _ArgumentCallable = Callable
+    _SignatureCallable = FunctionType
+
 
 # check_method 结果缓存：弱引用代码对象，模块或插件卸载后自动清理
 _implemented_cache: "weakref.WeakKeyDictionary[CodeType, bool]" = weakref.WeakKeyDictionary()
@@ -60,7 +68,7 @@ class ModuleHelper:
         filter_func: FilterFuncType = _default_filter,
     ) -> List[Any]:
         """加载包的一级模块，并返回通过过滤器的去重类对象。"""
-        submodules: list = []
+        submodules: list[type[object]] = []
         loaded_modules = set()
         packages = importlib.import_module(package_path)
         for _, package_name, _ in pkgutil.iter_modules(packages.__path__):
@@ -92,7 +100,7 @@ class ModuleHelper:
         submodules = []
         packages = importlib.import_module(package_path)
 
-        def reload_module_objects(target_module):
+        def reload_module_objects(target_module: ModuleType) -> list[type[object]]:
             """重载一个模块并返回过滤后的类对象。"""
             importlib.reload(target_module)
             return [
@@ -103,7 +111,7 @@ class ModuleHelper:
                 and filter_func(name, obj)
             ]
 
-        def reload_sub_modules(parent_module, parent_module_name):
+        def reload_sub_modules(parent_module: ModuleType, parent_module_name: str) -> None:
             """重载父包下能够成功导入的所有子模块。"""
             for _, sub_module_name, _ in pkgutil.walk_packages(
                 parent_module.__path__,
@@ -147,7 +155,7 @@ class ObjectUtils:
     """提供对象类型、函数实现和签名检查能力。"""
 
     @staticmethod
-    def is_obj(obj: Any):
+    def is_obj(obj: Any) -> bool:
         """判断值是否属于可展开的复合对象。"""
         if isinstance(obj, list) \
                 or isinstance(obj, dict) \
@@ -162,7 +170,7 @@ class ObjectUtils:
         return True
 
     @staticmethod
-    def is_objstr(obj: Any):
+    def is_objstr(obj: Any) -> bool:
         """判断字符串是否以常见复合对象字面量开头。"""
         if not isinstance(obj, str):
             return False
@@ -171,7 +179,7 @@ class ObjectUtils:
             or str(obj).startswith("(")
 
     @staticmethod
-    def arguments(func: Callable) -> int:
+    def arguments(func: _ArgumentCallable) -> int:
         """
         返回函数的参数个数
         """
@@ -212,7 +220,7 @@ class ObjectUtils:
             return not all(_is_placeholder_stmt(stmt) for stmt in node.body)
         except Exception:
             # 源代码分析失败时，进行字节码分析
-            code_obj = func.__code__  # type: ignore[attr-defined]
+            code_obj = func.__code__
             instructions = list(dis.get_instructions(code_obj))
             # 检查是否为仅返回None的简单结构
             if len(instructions) == 2:
@@ -221,7 +229,7 @@ class ObjectUtils:
                         second.opname == 'RETURN_VALUE'):
                     # 验证加载的常量是否为None
                     const_index = first.arg
-                    if (const_index < len(code_obj.co_consts) and
+                    if (const_index is not None and const_index < len(code_obj.co_consts) and
                             code_obj.co_consts[const_index] is None):
                         # 未实现的空函数
                         return False
@@ -229,7 +237,7 @@ class ObjectUtils:
             return True
 
     @staticmethod
-    def check_signature(func: FunctionType, *args) -> bool:
+    def check_signature(func: _SignatureCallable, *args: object) -> bool:
         """
         检查输出与函数的参数类型是否一致
         """

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` 通过局部可空类型声明保留
-既有搜索解析行为，并纳入严格清单；当前清单共 51 个文件（50 个生产文件和 1 个脚本）。
+既有搜索解析行为，并纳入严格清单；当前清单共 52 个文件（51 个生产文件和 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 源码量 | 371,931 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 |
+| Python 源码量 | 371,939 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 |
 | 长方法 | 309 个超过 80 行 | 本次 AST 扫描排除 `app/plugins/**`；61 个超过 150 行，17 个超过 250 行；新增函数仍受 C901/嵌套深度门禁约束 |
-| 全量 mypy 历史债务 | 9,114 / 502 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项，逐文件逐错误码无增长 |
+| 全量 mypy 历史债务 | 9,101 / 500 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项，逐文件逐错误码无增长 |
 | Ruff 历史诊断 | 100 | 低水位门禁通过，但规则集只覆盖 `E4/E7/E9/F/I` |
 | 覆盖率固定基线 | Application 80.00%，Domain 80.00% | Chain、Runtime、Agent、Adapter、Startup 未进入包级覆盖率门禁 |
 

mypy.ini

@@ -14,6 +14,7 @@ files =
     app/domain/tokens.py,
     app/domain/meta/infopath.py,
     app/foundation/url.py,
+    app/foundation/reflection.py,
     app/adapters/network/cloudflare.py,
     app/adapters/web/correlation.py,
     app/agent/contracts.py,

tests/fixtures/architecture/mypy-baseline.json

@@ -1295,14 +1295,6 @@
   "app/foundation/environment.py": {
     "no-any-return": 1
   },
-  "app/foundation/reflection.py": {
-    "index": 1,
-    "no-untyped-call": 2,
-    "no-untyped-def": 5,
-    "operator": 1,
-    "type-arg": 2,
-    "unused-ignore": 1
-  },
   "app/foundation/singleton.py": {
     "arg-type": 2,
     "misc": 2,
@@ -2458,9 +2450,6 @@
     "union-attr": 1,
     "var-annotated": 1
   },
-  "app/runtime/extensions/module/dispatcher.py": {
-    "arg-type": 1
-  },
   "app/runtime/extensions/module/manager.py": {
     "attr-defined": 1,
     "type-arg": 4

tests/test_reflection_signature_contract.py

@@ -0,0 +1,18 @@
+"""反射工具公开注解参与运行时签名校验的兼容性回归。"""
+
+import pytest
+
+from app.foundation.reflection import ObjectUtils
+
+
+@pytest.mark.parametrize("value, expected", [(lambda: None, True), (len, True), (1, False)])
+def test_argument_counter_preserves_runtime_callable_check(value, expected):
+    """参数计数器补齐静态类型后，仍能作为签名校验的目标函数。"""
+    assert ObjectUtils.check_signature(ObjectUtils.arguments, value) is expected
+
+
+def test_signature_checker_preserves_function_annotation():
+    """签名校验器仍保留函数对象注解，同时继续支持检查内建可调用对象。"""
+    assert ObjectUtils.check_signature(ObjectUtils.check_signature, lambda: None, 1)
+    assert not ObjectUtils.check_signature(ObjectUtils.check_signature, len, 1)
+    assert ObjectUtils.check_signature(len, [])