@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/code-quality/scripts/code_python.py

@@ -0,0 +1,536 @@
+# Python 专属体检：语言陷阱 + 数据分析（pandas）+ 安全。
+#
+# ── 为什么 Python 这一份能比 JS/Java 那两份更准 ──
+# JS 与 Java 走的是「掩码 + 括号配对」，那是权衡的结果（托管 Python 里没有可靠的
+# JS/Java 解析器，引入外部依赖会让体检在最需要它的时候要先装包）。
+# 但 Python 自己有标准库 `ast`——lens 早就把整棵语法树解析好了，只是一直没被用起来。
+#
+# 用 AST 能做到正则做不到的判断，而这些恰恰是 Python 最难查的坑：
+#
+#   class Cfg:                      ← 类属性是 list，**所有实例共享同一个对象**，
+#       items = []                    一个实例 append，别的实例全都看得见
+#
+#   fns = [lambda: i for i in range(3)]   ← 三个 lambda 全都返回 2：
+#                                            闭包捕获的是变量本身，不是当时的值
+#
+#   try: ...                        ← ValueError 是 Exception 的子类，
+#   except Exception: ...             第二个分支**永远不会执行**
+#   except ValueError: ...
+#
+#   for x in items:                 ← 遍历时删元素，会跳过紧随其后的那一个
+#       if bad(x): items.remove(x)
+#
+# 这四类正则几乎无从下手（要判断类型层级、作用域、名字绑定），AST 一查就准。
+#
+# ── 分组 ──
+#   logic.py-*      语言陷阱（共享可变、闭包、异常、迭代、名字遮蔽）
+#   framework.py-*  pandas 数据分析（链式赋值、已废弃 API、读文件丢精度）
+#   security.py-*   反序列化与子进程
+#
+# 误报纪律与主引擎一致：AST 判定为主，拿不准就不报。
+
+import ast
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# 遮蔽这些内置名会让后面的代码行为诡异，且报错信息完全不指向真正的原因
+_BUILTINS = {
+    'list', 'dict', 'set', 'tuple', 'str', 'int', 'float', 'bool', 'bytes',
+    'id', 'type', 'input', 'filter', 'map', 'max', 'min', 'sum', 'len', 'range',
+    'next', 'iter', 'open', 'file', 'hash', 'format', 'object', 'vars', 'dir',
+    'all', 'any', 'zip', 'sorted', 'reversed', 'print', 'compile', 'eval', 'exec',
+}
+# 这几个太常用作参数名，报了只会是噪声
+_BUILTIN_OK = {'id', 'type', 'format', 'input', 'object', 'all', 'any', 'next', 'hash', 'dir', 'vars'}
+
+
+def _unit_of(lens, line):
+    u = lens.unit_at(line)
+    return u.label if u else None
+
+
+def _name_of(node):
+    """把 ast 节点还原成可读的名字（`pd.read_csv` / `df.append`）。"""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _name_of(node.value)
+        return f'{base}.{node.attr}' if base else node.attr
+    return ''
+
+
+def _is_mutable_literal(node):
+    if isinstance(node, (ast.List, ast.Dict, ast.Set)):
+        return True
+    return isinstance(node, ast.Call) and _name_of(node.func) in ('list', 'dict', 'set', 'collections.OrderedDict')
+
+
+def _check_late_binding(loop_node, var, lens, ctx, out, add):
+    """循环体里定义的函数有没有捕获循环变量 var。"""
+    for sub in ast.walk(loop_node):
+        if not isinstance(sub, (ast.Lambda, ast.FunctionDef)):
+            continue
+        args = sub.args
+        bound = {a.arg for a in (args.posonlyargs + args.args + args.kwonlyargs)}
+        if var in bound:
+            continue                             # 用默认参数固定住了值，是正确写法
+        if any(isinstance(x, ast.Name) and x.id == var for x in ast.walk(sub)):
+            add(out, ctx, 'logic.py-late-binding', 'error', lens, sub.lineno,
+                f'循环里定义的函数引用了循环变量 `{var}` —— 闭包捕获的是**变量本身**而不是当时的值，'
+                f'循环结束后它们全都拿到最后一次的 `{var}`',
+                f'用默认参数当场固定：`lambda {var}={var}: ...`，或者用 functools.partial',
+                _unit_of(lens, sub.lineno))
+            return
+
+
+def check_python_traps(lens, ctx, out, add):
+    """Python 语言层面的坑，全部走 AST 判定。"""
+    tree = getattr(lens, '_ast', None)
+    if tree is None:
+        return                                   # 解析失败时不猜，主引擎已如实上报降级
+
+    # ── 类属性是可变对象：所有实例共享同一个，一个改全都变 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        is_dataclass = any('dataclass' in _name_of(d) for d in node.decorator_list)
+        for stmt in node.body:
+            targets, value = [], None
+            if isinstance(stmt, ast.Assign):
+                targets, value = stmt.targets, stmt.value
+            elif isinstance(stmt, ast.AnnAssign) and stmt.value is not None:
+                targets, value = [stmt.target], stmt.value
+            if not _is_mutable_literal(value):
+                continue
+            for t in targets:
+                if not isinstance(t, ast.Name) or t.id.isupper():
+                    continue                     # 全大写按常量看待（约定上不会去改它）
+                if is_dataclass:
+                    add(out, ctx, 'logic.py-dataclass-mutable', 'error', lens, stmt.lineno,
+                        f'dataclass `{node.name}` 的字段 `{t.id}` 用可变对象做默认值 —— '
+                        'Python 会直接报 ValueError，或者（旧版本里）所有实例共享同一个对象',
+                        f'改成 `{t.id}: list = field(default_factory=list)`', node.name)
+                else:
+                    add(out, ctx, 'logic.py-mutable-class-attr', 'error', lens, stmt.lineno,
+                        f'`{node.name}.{t.id}` 是类属性且是可变对象 —— '
+                        '**所有实例共享同一个**，任何一个实例 append/update，其它实例全都看得见',
+                        f'挪进 `__init__`：`self.{t.id} = []`。'
+                        '这个坑在单实例场景下完全正常，等到第二个实例出现才暴露', node.name)
+
+    # ── 循环里定义的函数捕获循环变量：延迟绑定，最后全都拿到最后一次的值 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.For, ast.AsyncFor)):
+            continue
+        # 元组解包同样要覆盖：`for idx, row in df.iterrows():` 里的闭包捕获 row，
+        # 只认单变量循环的话，pandas 场景下这条规则基本不会响——而那正是它最该响的地方。
+        if isinstance(node.target, ast.Name):
+            loop_vars = [node.target.id]
+        elif isinstance(node.target, (ast.Tuple, ast.List)):
+            loop_vars = [e.id for e in node.target.elts if isinstance(e, ast.Name)]
+        else:
+            continue
+        if not loop_vars:
+            continue
+        for var in loop_vars:
+            _check_late_binding(node, var, lens, ctx, out, add)
+
+
+    # ── except 顺序：父类写在前面，后面的子类分支永远执行不到 ──
+    _HIER = {
+        'Exception': {'ValueError', 'TypeError', 'KeyError', 'IndexError', 'AttributeError',
+                      'OSError', 'IOError', 'RuntimeError', 'ZeroDivisionError', 'StopIteration',
+                      'ArithmeticError', 'LookupError', 'NameError', 'ImportError', 'FileNotFoundError'},
+        'BaseException': {'Exception', 'KeyboardInterrupt', 'SystemExit', 'GeneratorExit'},
+        'OSError': {'FileNotFoundError', 'PermissionError', 'FileExistsError', 'TimeoutError',
+                    'ConnectionError', 'IsADirectoryError', 'NotADirectoryError'},
+        'LookupError': {'KeyError', 'IndexError'},
+        'ArithmeticError': {'ZeroDivisionError', 'OverflowError', 'FloatingPointError'},
+        'ValueError': {'UnicodeDecodeError', 'UnicodeEncodeError'},
+    }
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Try):
+            continue
+        seen = []
+        for handler in node.handlers:
+            names = []
+            if handler.type is None:
+                names = ['BaseException']
+            elif isinstance(handler.type, ast.Tuple):
+                names = [_name_of(e).split('.')[-1] for e in handler.type.elts]
+            else:
+                names = [_name_of(handler.type).split('.')[-1]]
+            for nm in names:
+                for prev in seen:
+                    if nm in _HIER.get(prev, ()) or prev == 'BaseException':
+                        add(out, ctx, 'logic.py-except-order', 'error', lens, handler.lineno,
+                            f'`except {nm}` 排在 `except {prev}` 后面，而 {nm} 是 {prev} 的子类 —— '
+                            '**这个分支永远不会执行**，异常会被前面那个捕走',
+                            f'把 `except {nm}` 挪到 `except {prev}` 前面：'
+                            '异常分支要从最具体排到最宽泛', _unit_of(lens, handler.lineno))
+                        break
+            seen.extend(names)
+
+    # ── 遍历时增删同一个容器：会跳过元素，或直接抛 RuntimeError ──
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.For, ast.AsyncFor)) or not isinstance(node.iter, ast.Name):
+            continue
+        coll = node.iter.id
+        for sub in ast.walk(node):
+            if not isinstance(sub, ast.Call) or not isinstance(sub.func, ast.Attribute):
+                continue
+            if sub.func.attr not in ('remove', 'pop', 'append', 'insert', 'clear', 'update'):
+                continue
+            if _name_of(sub.func.value) != coll:
+                continue
+            add(out, ctx, 'logic.py-mutate-during-iteration', 'error', lens, sub.lineno,
+                f'一边遍历 `{coll}` 一边 `{sub.func.attr}()` 它 —— '
+                '列表会**跳过**紧随其后的元素（下标已经前移），字典直接抛 RuntimeError',
+                f'遍历副本 `for x in list({coll}):`，或用列表推导重建：'
+                f'`{coll} = [x for x in {coll} if 条件]`', _unit_of(lens, sub.lineno))
+            break
+
+    # ── is 比较字面量：靠的是对象缓存，小数字/短字符串"碰巧"为真 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Compare):
+            continue
+        for op, cmp in zip(node.ops, node.comparators):
+            if not isinstance(op, (ast.Is, ast.IsNot)):
+                continue
+            if isinstance(cmp, ast.Constant) and cmp.value is not None and not isinstance(cmp.value, bool):
+                add(out, ctx, 'logic.py-is-literal', 'error', lens, node.lineno,
+                    f'用 `is` 比较字面量 `{cmp.value!r}` —— `is` 比的是**同一个对象**，'
+                    '小整数和短字符串因为有缓存会"碰巧"为真，换个值或换个来源就突然为假',
+                    '比较值用 `==`；`is` 只留给 None / True / False 这三个单例',
+                    _unit_of(lens, node.lineno))
+            # 反过来：== None / == True 应该用 is
+        for op, cmp in zip(node.ops, node.comparators):
+            if not isinstance(op, (ast.Eq, ast.NotEq)):
+                continue
+            if isinstance(cmp, ast.Constant) and (cmp.value is None or isinstance(cmp.value, bool)):
+                add(out, ctx, 'logic.py-eq-singleton', 'info', lens, node.lineno,
+                    f'用 `==` 比较 `{cmp.value!r}` —— 它是单例，应该用 `is`',
+                    f'写成 `is {cmp.value!r}`；`== True` 还会把 1 也算作真，'
+                    '而 `is True` 不会', _unit_of(lens, node.lineno))
+
+    # ── except 里 raise 新异常不带 from：原始堆栈就此丢失 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ExceptHandler):
+            continue
+        for sub in ast.walk(node):
+            if not isinstance(sub, ast.Raise) or sub.cause is not None:
+                continue
+            if sub.exc is None:
+                continue                         # 裸 raise 是重新抛出原异常，正确
+            add(out, ctx, 'logic.py-raise-without-from', 'warn', lens, sub.lineno,
+                '在 except 里抛出新异常却没有 `from` —— 原始异常的堆栈会被截断，'
+                '排查时只看得到"包装后"的那一层',
+                '写成 `raise 新异常(...) from e`；确实要隐藏内层细节就写 `from None`，'
+                '那也是一个明确的决定而不是遗漏', _unit_of(lens, sub.lineno))
+            break
+
+    # ── 遮蔽内置名：后面用到那个内置函数时会得到诡异的报错 ──
+    for node in ast.walk(tree):
+        target = None
+        if isinstance(node, ast.Assign) and len(node.targets) == 1:
+            target = node.targets[0]
+        elif isinstance(node, (ast.For, ast.AsyncFor)):
+            target = node.target
+        if not isinstance(target, ast.Name):
+            continue
+        if target.id in _BUILTINS and target.id not in _BUILTIN_OK:
+            add(out, ctx, 'logic.py-shadow-builtin', 'warn', lens, node.lineno,
+                f'变量名 `{target.id}` 遮蔽了同名内置函数 —— '
+                f'这一行之后再想调用 `{target.id}()` 就会报"不可调用"，而错误信息完全不指向这里',
+                f'换个名字，比如 `{target.id}_` 或更具体的 `user_{target.id}`',
+                _unit_of(lens, node.lineno))
+
+    # ── 生产代码里用 assert 做校验：python -O 会把它整行删掉 ──
+    if not lens.is_test:
+        # `if __name__ == '__main__':` 里的 assert 是脚本自测，不是生产校验。
+        # 判定要用 AST 的节点范围——往上找一行的写法只在 assert 紧贴 if 时才对，
+        # 而自测块里通常有十几行。
+        main_ranges = []
+        for top in tree.body:
+            if not isinstance(top, ast.If):
+                continue
+            test = top.test
+            if isinstance(test, ast.Compare) and _name_of(test.left) == '__name__':
+                last = max((getattr(x, 'end_lineno', x.lineno) or x.lineno) for x in top.body)
+                main_ranges.append((top.lineno, last))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Assert):
+                continue
+            fn = lens.unit_at(node.lineno)
+            # 自测函数的命名约定不止 `test_xxx` 一种：本仓库大量用 `selftest` / `self_test` / `_selftest`，
+            # 只认「以 test 开头」会把 117 条自测断言全报成生产校验。
+            # `(^|_)` 这个前缀不能省——否则 `latest_config` 这类名字也会被当成测试。
+            if fn and re.search(r'(^|_)(self_?)?tests?(_|$)', fn.name.lower()):
+                continue
+            if any(a <= node.lineno <= b for a, b in main_ranges):
+                continue
+            add(out, ctx, 'logic.py-assert-in-production', 'warn', lens, node.lineno,
+                '用 `assert` 做运行时校验 —— 以 `python -O` 启动时**整行会被删掉**，校验静默消失',
+                '参数校验改成 `if not 条件: raise ValueError(...)`；'
+                'assert 只用来表达"这里不可能发生"的内部不变量', _unit_of(lens, node.lineno))
+
+    # ── type(x) == T：拿不到继承关系 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Compare) or not node.ops:
+            continue
+        if not isinstance(node.ops[0], (ast.Eq, ast.NotEq)):
+            continue
+        if isinstance(node.left, ast.Call) and _name_of(node.left.func) == 'type':
+            add(out, ctx, 'logic.py-type-compare', 'warn', lens, node.lineno,
+                '用 `type(x) == T` 判类型 —— 子类实例会被判为不匹配',
+                '改用 `isinstance(x, T)`；确实要排除子类（少见）就把这个意图写进注释',
+                _unit_of(lens, node.lineno))
+
+
+# ── 数据分析（pandas）、安全、异步 ───────────────────────────────────────────
+# pandas 这一组的价值特别高，因为它的事故**不改变外观、只改变数字**：
+# 读进来的时候前导零没了、大数字变成科学计数法、链式赋值静默不生效——
+# 表格看上去一切正常，只是数对不上，而人盯着屏幕是看不出来的。
+_PANDAS_READERS = ('read_csv', 'read_excel', 'read_table', 'read_json')
+_BLOCKING_IN_ASYNC = {
+    'time.sleep': 'asyncio.sleep',
+    'requests.get': 'httpx/aiohttp 的异步客户端',
+    'requests.post': 'httpx/aiohttp 的异步客户端',
+    'requests.put': 'httpx/aiohttp 的异步客户端',
+    'requests.delete': 'httpx/aiohttp 的异步客户端',
+    'subprocess.run': 'asyncio.create_subprocess_exec',
+    'subprocess.call': 'asyncio.create_subprocess_exec',
+    'subprocess.check_output': 'asyncio.create_subprocess_exec',
+}
+
+
+def _kw(call, name):
+    """取调用的某个关键字实参节点；没有返回 None。"""
+    for k in call.keywords:
+        if k.arg == name:
+            return k.value
+    return None
+
+
+def check_python_data_and_security(lens, ctx, out, add):
+    """pandas 用法、反序列化与子进程安全、异步里的阻塞调用。"""
+    tree = getattr(lens, '_ast', None)
+    if tree is None:
+        return
+    text = lens.text
+    uses_pandas = 'pandas' in text or re.search(r'\bpd\.', text)
+
+    for node in ast.walk(tree):
+        # ── 链式赋值：`df[a][b] = x` 改的是临时副本，原表没变（SettingWithCopyWarning） ──
+        if isinstance(node, ast.Assign):
+            for t in node.targets:
+                if (isinstance(t, ast.Subscript) and isinstance(t.value, ast.Subscript)
+                        and uses_pandas):
+                    add(out, ctx, 'framework.py-pandas-chained-assign', 'error', lens, node.lineno,
+                        '链式下标赋值 `df[...][...] = ...` —— pandas 很可能改的是一份**临时副本**，'
+                        '原表根本没变，而且只会给个 SettingWithCopyWarning，不报错',
+                        '用 `.loc` 一次定位：`df.loc[行条件, "列名"] = 值`。'
+                        '这类问题最坏的形态是"程序跑完了、结果是错的、没有任何提示"',
+                        _unit_of(lens, node.lineno))
+
+        if not isinstance(node, ast.Call):
+            continue
+        fname = _name_of(node.func)
+        short = fname.split('.')[-1]
+
+        # ── 读表不指定 dtype：前导零丢失、长编号变科学计数法 ──
+        if short in _PANDAS_READERS and uses_pandas:
+            # `**kw` 展开时 dtype 可能就在里面，看不见也不能断言它没传
+            splatted = any(k.arg is None for k in node.keywords)
+            if not splatted and _kw(node, 'dtype') is None and _kw(node, 'converters') is None:
+                add(out, ctx, 'framework.py-read-no-dtype', 'warn', lens, node.lineno,
+                    f'`{short}()` 没有指定 dtype —— pandas 会自动推断类型，'
+                    '「007」这类前导零编号会变成数字 7，18 位的单号会变成科学计数法**且精度已经丢了**',
+                    '编号/证件号/手机号一律 `dtype=str`（或 `dtype={"单号": str}`）。'
+                    '这一步省下来，后面对账对不上时已经救不回来，只能重新导一次数据',
+                    _unit_of(lens, node.lineno))
+
+        # ── DataFrame.append：pandas 2.0 已经删掉了这个方法 ──
+        # 判 DataFrame.append 不能靠变量名猜：`tables.append(rows)` 是再普通不过的 list.append，
+        # 却会被 `table\w*` 这种模式捞走。可靠信号有两个——
+        #   ① 传了 `ignore_index=`（list.append 根本不接受关键字参数）；
+        #   ② 变量名严格就是 df / xxx_df / df_xxx。
+        base = _name_of(node.func.value) if isinstance(node.func, ast.Attribute) else ''
+        looks_df = bool(re.fullmatch(r'df|df_\w+|\w+_df|dataframe', base, re.I))
+        if short == 'append' and uses_pandas and (_kw(node, 'ignore_index') is not None or looks_df):
+            add(out, ctx, 'framework.py-pandas-append', 'error', lens, node.lineno,
+                '`DataFrame.append()` 在 pandas 2.0 已被移除，调用会直接 AttributeError',
+                '改用 `pd.concat([df1, df2], ignore_index=True)`；'
+                '循环里逐行 append 更要改成先收集成列表、最后一次性 concat（否则是 O(n²)）',
+                _unit_of(lens, node.lineno))
+
+        # ── iterrows：每行都构造一个 Series，大表上慢几十倍 ──
+        if short == 'iterrows' and uses_pandas:
+            add(out, ctx, 'framework.py-pandas-iterrows', 'info', lens, node.lineno,
+                '`iterrows()` 逐行遍历：每一行都会构造一个 Series 对象，几万行就能感觉到卡',
+                '优先向量化（`df["c"] = df["a"] * df["b"]`）；'
+                '确实要逐行就用 `itertuples()`（快一个量级），或 `df.apply(..., axis=1)`',
+                _unit_of(lens, node.lineno))
+
+        # ── inplace=True：既不省内存，还让链式写法断掉，pandas 官方已在劝退 ──
+        if uses_pandas:
+            inplace = _kw(node, 'inplace')
+            if isinstance(inplace, ast.Constant) and inplace.value is True:
+                add(out, ctx, 'framework.py-pandas-inplace', 'info', lens, node.lineno,
+                    f'`{short}(..., inplace=True)` —— 它并不省内存（内部照样复制），'
+                    '却让返回值变成 None，链式写法一接就断，也更容易误改到副本',
+                    '改成赋值回去：`df = df.xxx(...)`', _unit_of(lens, node.lineno))
+
+        # ── subprocess shell=True：拼接的命令会被 shell 解释 ──
+        if fname.startswith('subprocess.') or short in ('run', 'call', 'Popen', 'check_output'):
+            shell = _kw(node, 'shell')
+            if isinstance(shell, ast.Constant) and shell.value is True:
+                first = node.args[0] if node.args else None
+                dynamic = first is not None and not isinstance(first, ast.Constant)
+                add(out, ctx, 'security.py-subprocess-shell',
+                    'error' if dynamic else 'warn', lens, node.lineno,
+                    'subprocess 用了 `shell=True`'
+                    + ('，并且命令是拼出来的 —— 参数里的 `;` `|` `$()` 都会被 shell 执行'
+                       if dynamic else '（本次命令是常量，风险有限）'),
+                    '传列表而不是字符串：`subprocess.run(["git", "checkout", name])`，'
+                    '不经 shell 解析就没有注入面', _unit_of(lens, node.lineno))
+
+        # ── yaml.load 不带 Loader：能构造出任意 Python 对象 ──
+        if fname in ('yaml.load', 'load') and 'yaml' in text:
+            if _kw(node, 'Loader') is None and len(node.args) < 2:
+                add(out, ctx, 'security.py-yaml-load', 'error', lens, node.lineno,
+                    '`yaml.load()` 没有指定 Loader —— 默认加载器能构造任意 Python 对象，'
+                    '解析不可信的 YAML 等同于执行它',
+                    '用 `yaml.safe_load()`；确实需要自定义标签再显式传 Loader',
+                    _unit_of(lens, node.lineno))
+
+        # ── pickle 反序列化：等同于执行对方给的代码 ──
+        if fname in ('pickle.loads', 'pickle.load', 'cPickle.loads'):
+            add(out, ctx, 'security.py-pickle', 'warn', lens, node.lineno,
+                f'`{fname}()` 反序列化 —— pickle 会在加载时执行对象里的构造逻辑，'
+                '来源不可信时等同于任意代码执行',
+                '换成 JSON 等只描述数据的格式；确实要用 pickle 就限定只读自己写出的文件，'
+                '并在注释里写明这个前提', _unit_of(lens, node.lineno))
+
+    # ── async 函数里的阻塞调用：整个事件循环被卡住，所有并发一起停 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.AsyncFunctionDef):
+            continue
+        for sub in ast.walk(node):
+            if not isinstance(sub, ast.Call):
+                continue
+            fname = _name_of(sub.func)
+            better = _BLOCKING_IN_ASYNC.get(fname)
+            if better is None and fname == 'open':
+                better = 'aiofiles，或把文件 IO 丢进 run_in_executor'
+            if better is None:
+                continue
+            add(out, ctx, 'logic.py-blocking-in-async', 'error', lens, sub.lineno,
+                f'async 函数 `{node.name}` 里调用了阻塞的 `{fname}()` —— '
+                '事件循环被整个卡住，**同一个循环上的所有协程一起停**，异步就失去了意义',
+                f'改用 {better}；实在只有同步库可用就 `await loop.run_in_executor(None, ...)`',
+                node.name)
+
+    # ── open 不用 with：异常路径上句柄不会关 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assign) or not isinstance(node.value, ast.Call):
+            continue
+        if _name_of(node.value.func) != 'open':
+            continue
+        add(out, ctx, 'logic.py-open-without-with', 'warn', lens, node.lineno,
+            '`open()` 的结果直接赋给变量，没有走 `with` —— 中途抛异常时文件不会被关闭',
+            '写成 `with open(...) as f:`；句柄泄漏平时看不出来，'
+            '到达上限时整个进程一起打不开文件', _unit_of(lens, node.lineno))
+
+    # ── logging 用 f-string：无论日志级别开没开，字符串都先拼好了 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        fname = _name_of(node.func)
+        if not re.search(r'(^|\.)(log|logger|logging|LOG|LOGGER)\.(debug|info|warning|error|exception|critical)$',
+                         fname):
+            continue
+        if node.args and isinstance(node.args[0], ast.JoinedStr):
+            add(out, ctx, 'logic.py-logging-fstring', 'info', lens, node.lineno,
+                'logging 的消息用了 f-string —— 参数会**无条件先求值拼接**，'
+                '即使这条日志因为级别不够根本不会输出',
+                '改成惰性占位：`log.info("处理了 %s 条", n)`。'
+                '热路径上的 debug 日志尤其要注意这一条', _unit_of(lens, node.lineno))
+
+    # ── finally 里 return：会把正在抛的异常吞掉 ──
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Try) or not node.finalbody:
+            continue
+        for sub in node.finalbody:
+            for x in ast.walk(sub):
+                if isinstance(x, (ast.Return, ast.Break, ast.Continue)):
+                    add(out, ctx, 'logic.py-return-in-finally', 'error', lens, x.lineno,
+                        'finally 块里 return/break/continue —— '
+                        '会把 try 块中正在抛出的异常直接丢弃，故障现场就此消失',
+                        'finally 只做清理；要改返回值就在 try 里改', _unit_of(lens, x.lineno))
+                    break
+
+
+# ── 与 dev-python「常见坑 TOP」对齐的几条 ──────────────────────────────────
+# 同 Java 那一轮的做法：把技能文档里「评审自查单」上的条目变成机器每次都查。
+# 这几条的共同点是**在开发机上永远正常**，换个操作系统、换个时区、上了生产才出事。
+def check_python_pitfalls(lens, ctx, out, add):
+    """dev-python 技能里「评审必查」的那几条。"""
+    tree = getattr(lens, '_ast', None)
+    if tree is None:
+        return
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        fname = _name_of(node.func)
+
+        # ── open() 不写 encoding：Windows 默认 GBK，读 UTF-8 文件当场乱码或抛异常 ──
+        if fname == 'open':
+            mode = node.args[1] if len(node.args) > 1 else _kw(node, 'mode')
+            is_binary = isinstance(mode, ast.Constant) and 'b' in str(mode.value)
+            if not is_binary and _kw(node, 'encoding') is None:
+                add(out, ctx, 'logic.py-open-no-encoding', 'warn', lens, node.lineno,
+                    '`open()` 没写 encoding —— 它取的是**操作系统默认编码**，'
+                    'Windows 上是 GBK，读 UTF-8 文件当场乱码或抛 UnicodeDecodeError',
+                    '一律显式 `encoding="utf-8"`。这个 bug 在开发机（macOS/Linux）上永远复现不了，'
+                    '只在用户那边炸', _unit_of(lens, node.lineno))
+
+        # ── datetime.now() 不带时区：naive 时间一旦跨时区或存库就说不清是几点 ──
+        if fname in ('datetime.now', 'datetime.datetime.now', 'datetime.utcnow',
+                     'datetime.datetime.utcnow'):
+            if fname.endswith('utcnow'):
+                add(out, ctx, 'logic.py-naive-datetime', 'warn', lens, node.lineno,
+                    '`utcnow()` 返回的是**不带时区**的 datetime（已废弃）—— '
+                    '它看起来是 UTC，但对象上没有这个信息，一转换就错',
+                    '改用 `datetime.now(timezone.utc)`', _unit_of(lens, node.lineno))
+            elif not node.args and not node.keywords:
+                add(out, ctx, 'logic.py-naive-datetime', 'warn', lens, node.lineno,
+                    '`datetime.now()` 不带时区 —— 得到的是 naive 时间，'
+                    '存库、跨服务传递、跨时区比较时没人说得清它到底是哪个时区的几点',
+                    '写成 `datetime.now(timezone.utc)`，展示时再转本地时区',
+                    _unit_of(lens, node.lineno))
+
+        # ── Decimal(浮点)：和 Java 的 new BigDecimal(double) 是同一个坑 ──
+        if fname in ('Decimal', 'decimal.Decimal') and node.args:
+            arg = node.args[0]
+            if isinstance(arg, ast.Constant) and isinstance(arg.value, float):
+                add(out, ctx, 'logic.py-decimal-float', 'error', lens, node.lineno,
+                    f'`Decimal({arg.value})` 用浮点构造 —— 误差在进入 Decimal 之前就已经产生了，'
+                    f'结果是 {arg.value} 的二进制近似值而不是你写的那个数',
+                    '用字符串构造：`Decimal("0.1")`。'
+                    '钱一旦这样算错，对账时差的那几分钱要查很久', _unit_of(lens, node.lineno))
+
+        # ── os.path.join 后段是绝对路径时会把前面全部丢掉 ──
+        if fname == 'os.path.join' and len(node.args) >= 2:
+            for extra in node.args[1:]:
+                if isinstance(extra, ast.Constant) and isinstance(extra.value, str) \
+                        and extra.value.startswith(('/', '\\')):
+                    add(out, ctx, 'logic.py-join-absolute', 'error', lens, node.lineno,
+                        f'`os.path.join(..., "{extra.value}")` 的后段以斜杠开头 —— '
+                        'join 遇到绝对路径会**丢弃前面所有部分**，结果完全不是拼接',
+                        '把后段开头的斜杠去掉，或改用 `pathlib.Path(a) / b`（同样有这个语义，'
+                        '但写法上更容易看出来）', _unit_of(lens, node.lineno))
+                    break