@huicai/cli 2026.814.0 → 2026.1019.0

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

@@ -0,0 +1,371 @@
+# C# 专属体检：异步陷阱 + 异常与资源 + LINQ + EF Core / ASP.NET Core。
+#
+# ── C# 的事故形态 ──
+# 和 Java 很像——编译通过、运行不报错、出事时离现场很远。但有几个是 C# 独有的，
+# 而且都属于「写错了反而更像对的」那一类：
+#
+#   async void Handler()        ← 异常**没有任何办法捕获**，直接终结进程。
+#                                  改成 async Task 只差四个字母，行为天差地别。
+#   var x = FooAsync().Result;  ← 在有同步上下文的环境（ASP.NET 经典、WinForms、WPF）
+#                                  必然死锁，而在控制台程序里一切正常——本地测不出来。
+#   throw ex;                   ← 堆栈从这一行**重新开始**，原始出错位置就此丢失。
+#                                  少写两个字母（`throw;`）才是对的。
+#   DateTime.Now                ← 服务器换个时区、夏令时切换，所有时间计算一起错。
+#   double 算钱                 ← 和 Java 的 double、Python 的 float 是同一个坑。
+#
+# ── 解析前提 ──
+# C# 走「掩码 + 括号配对」，和 Java 同一套（parse_braces 的 csharp 分支）。
+# 改造前它落在 js 与 java 两个分支的空隙里：**方法一个都解析不到，parse_ok 却是 True**，
+# 于是所有基于函数的规则静默失效，而报告照样说「未发现问题」。
+#
+# ── 一条必须说明的局限 ──
+# 前四轮（JS/Java/Python/Vue）的误报都是在本仓库的真实代码上治出来的：
+# Java 在 836 个文件上从 237 条假必修降到个位数，Python 在 94 个文件上从 136 条降到 19 条。
+# **本仓库没有 C# 代码**，这一组的误报率只经过了压测台的合规样本验证，
+# 没有真实项目的检验。判据因此刻意取得比 Java 那组更保守——拿不准一律不报。
+
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# ── 异步 ────────────────────────────────────────────────────────────────────
+_RE_BLOCKING_ASYNC = re.compile(
+    r'\.\s*(Result)\b|\.\s*(Wait)\s*\(\s*\)|\.\s*GetAwaiter\s*\(\s*\)\s*\.\s*(GetResult)\s*\(\s*\)')
+# ── 异常 ────────────────────────────────────────────────────────────────────
+_RE_THROW_EX = re.compile(r'\bcatch\s*\(\s*\w+\s+(\w+)\s*\)')
+# ── 时间与精度 ──────────────────────────────────────────────────────────────
+_RE_DATETIME_NOW = re.compile(r'\bDateTime(?:Offset)?\s*\.\s*(Now|Today)\b')
+_RE_MONEY_TYPE = re.compile(
+    r'\b(double|float)\s+(\w*(?:[Aa]mount|[Pp]rice|[Mm]oney|[Ff]ee|[Cc]ost|[Bb]alance|[Tt]otal|[Ss]alary|[Tt]ax)\w*)\b')
+# ── LINQ ────────────────────────────────────────────────────────────────────
+_RE_COUNT_COMPARE = re.compile(r'\.\s*Count\s*\(\s*\)\s*(>|>=|==|!=)\s*0\b|\b0\s*(<|<=)\s*\w+\.\s*Count\s*\(\s*\)')
+_RE_LINQ_DEFERRED = re.compile(r'\b(?:var|IEnumerable<[^>]+>)\s+(\w+)\s*=\s*[^;]*\.\s*(?:Where|Select|OrderBy|OrderByDescending|Take|Skip|SelectMany|Distinct)\s*\(')
+_RE_ENUMERATE = re.compile(r'\.\s*(Count|Any|First|FirstOrDefault|Last|LastOrDefault|Single|SingleOrDefault|Sum|Max|Min|Average|ToList|ToArray|ToDictionary)\s*\(')
+# ── 并发 ────────────────────────────────────────────────────────────────────
+_RE_LOCK_BAD = re.compile(r'\block\s*\(\s*(this|typeof\s*\([^)]*\)|"[^"]*")\s*\)')
+# ── 文化 ────────────────────────────────────────────────────────────────────
+_RE_PARSE_NO_CULTURE = re.compile(r'\b(?:decimal|double|float|int|long|DateTime)\s*\.\s*(Parse|TryParse)\s*\(')
+# ── EF Core / ASP.NET Core ──────────────────────────────────────────────────
+_RE_SQL_RAW = re.compile(r'\.\s*(FromSqlRaw|ExecuteSqlRaw|FromSql)\s*\(')
+_RE_DI_SINGLETON = re.compile(r'\.\s*AddSingleton\s*<\s*([\w.<>, ]+?)\s*>')
+_RE_DB_QUERY = re.compile(
+    r'\.\s*(?:ToListAsync|FirstOrDefaultAsync|SingleOrDefaultAsync|FindAsync|AnyAsync|CountAsync'
+    r'|ToList|FirstOrDefault|SingleOrDefault|Find)\s*\(')
+
+
+def _line_of(lens, off):
+    return lens.text.count('\n', 0, off) + 1
+
+
+def _unit_of(lens, line):
+    u = lens.unit_at(line)
+    return u.label if u else None
+
+
+def _block_after(code, brace_off, limit=4000):
+    """从 '{' 取到配对 '}' 的内容。"""
+    depth = 0
+    for i in range(brace_off, min(len(code), brace_off + limit)):
+        if code[i] == '{':
+            depth += 1
+        elif code[i] == '}':
+            depth -= 1
+            if depth == 0:
+                return code[brace_off:i]
+    return code[brace_off:brace_off + limit]
+
+
+def check_csharp_traps(lens, ctx, out, add):
+    """C# 的异步、异常、资源、时间精度这几类坑。"""
+    code = lens.code
+
+    for u in lens.functions():
+        mods = set(u.modifiers)
+
+        # ── async void：异常逃出方法后没有任何人能接住，直接终结进程 ──
+        # 测试文件里的 async void 另有一条规则（后果不同：不是崩进程，是用例假绿），
+        # 两条都报只会让人看到两遍同一件事。
+        if 'async' in mods and (u.ret_type or '').strip() == 'void' and not lens.is_test:
+            is_event_handler = bool(re.search(r'(EventArgs|sender)', ' '.join(u.params)))
+            add(out, ctx, 'logic.cs-async-void', 'error', lens, u.start,
+                f'`{u.label}` 是 `async void` —— 它返回的不是 Task，'
+                '调用方无法 await、无法 try/catch，方法内抛出的异常会直接**终结整个进程**',
+                ('事件处理器确实只能是 async void，那就把整个方法体包在 try/catch 里，'
+                 '一个异常都不许逃出去') if is_event_handler
+                else '改成 `async Task`。只有事件处理器例外，而那时必须自己兜住所有异常',
+                u.label)
+
+        # ── async 方法里一个 await 都没有：白加了状态机，还会误导调用方 ──
+        if 'async' in mods and not re.search(r'\bawait\b', u.body):
+            add(out, ctx, 'logic.cs-async-no-await', 'warn', lens, u.start,
+                f'`{u.label}` 标了 async 却没有任何 await —— 编译器会生成状态机但没有异步收益，'
+                '而调用方看到 Task 会以为它真的是异步的',
+                '没有异步操作就去掉 async（直接 `return Task.FromResult(x)`）；'
+                '本该有 await 的话，检查是不是漏了', u.label)
+
+        # ── catch (Ex e) { … throw e; }：堆栈从这一行重新开始，原始出错位置丢失 ──
+        for cm in _RE_THROW_EX.finditer(u.body):
+            var = cm.group(1)
+            brace = u.body.find('{', cm.end())
+            if brace < 0:
+                continue
+            blk = _block_after(u.body, brace)
+            tm = re.search(rf'\bthrow\s+{re.escape(var)}\s*;', blk)
+            if not tm:
+                continue
+            ln = u.line_at(brace + tm.start())
+            add(out, ctx, 'logic.cs-throw-ex', 'error', lens, ln,
+                f'`throw {var};` —— 这会把异常的堆栈**从这一行重新开始**，'
+                '原始的出错位置就此丢失，线上只看得到这个 catch 在哪',
+                '要原样重抛就写 `throw;`（不带变量）；'
+                f'要包一层就写 `throw new XxxException("…", {var});` 把原异常作为 innerException 传进去',
+                u.label)
+
+        # ── 循环里查库：典型的 N+1 ──
+        for lm in re.finditer(r'\b(?:foreach|for|while)\s*\([^)]*\)\s*\{', u.body):
+            blk = _block_after(u.body, lm.end() - 1)
+            qm = _RE_DB_QUERY.search(blk)
+            if not qm:
+                continue
+            if not re.search(r'\b(_?(?:db|context|ctx|repo|repository)\w*)\s*\.', blk, re.I):
+                continue
+            ln = u.line_at(lm.start())
+            add(out, ctx, 'logic.cs-query-in-loop', 'warn', lens, ln,
+                '循环体里在查数据库 —— 每转一圈发一次查询（N+1）：'
+                '十条数据十次往返，一千条就是一千次，本地小数据量时完全看不出来',
+                '循环外一次性取回（`Where(x => ids.Contains(x.Id))`），'
+                '或者用 `Include` 把关联数据一起带出来，再在内存里组装', u.label)
+
+    # ── .Result / .Wait()：在有同步上下文的环境里必然死锁 ──
+    for m in _RE_BLOCKING_ASYNC.finditer(code):
+        what = next((g for g in m.groups() if g), '')
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        if re.search(r'\b(Task\.Run|Main\s*\(|\.ConfigureAwait)', line_txt):
+            continue                      # Main 里同步等待、或已显式切上下文的，属于有意识的用法
+        add(out, ctx, 'logic.cs-blocking-async', 'error', lens, ln,
+            f'用 `.{what}` 同步等待异步结果 —— 在有同步上下文的环境'
+            '（ASP.NET 经典管线、WinForms、WPF）**必然死锁**：'
+            '当前线程被占住，而续体正等着回到这个线程',
+            '一路 await 到顶（`await FooAsync()`，调用方也改成 async）。'
+            '这个坑最难受的地方是：控制台程序和单元测试里跑得好好的，上了 Web 才死', _unit_of(lens, ln))
+
+    # ── DateTime.Now：带本地时区，换服务器/夏令时就全错 ──
+    for m in _RE_DATETIME_NOW.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.cs-datetime-now', 'warn', lens, ln,
+            f'`DateTime.{m.group(1)}` 取的是**服务器本地时间** —— '
+            '换个时区部署、或者夏令时切换那两天，所有时间计算与比较一起出错',
+            '存储与计算一律 `DateTime.UtcNow`（或 `DateTimeOffset.UtcNow`，它连偏移量一起带着），'
+            '只在展示给用户时才转本地时区', _unit_of(lens, ln))
+
+    # ── double/float 算钱 ──
+    for m in _RE_MONEY_TYPE.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.cs-double-for-money', 'error', lens, ln,
+            f'用 `{m.group(1)}` 声明金额字段 `{m.group(2)}` —— 二进制浮点存不下 0.1，'
+            '累加几次就会差出分，对账时查不出来源',
+            '金额一律用 `decimal`（C# 的十进制类型，正是为钱设计的）；'
+            '与 Java 的 BigDecimal、Python 的 Decimal 是同一件事', _unit_of(lens, ln))
+
+    # ── lock(this) / lock(typeof(X)) / lock("字符串")：锁对象是公开的，外部也能锁它 ──
+    for m in _RE_LOCK_BAD.finditer(code):
+        ln = _line_of(lens, m.start())
+        target = m.group(1)
+        why = ('字符串是驻留的，全进程共享同一个实例，不相干的代码可能锁到同一把锁'
+               if target.startswith('"') else
+               '这个对象外部拿得到，别的代码也能锁它，很容易凑成死锁')
+        add(out, ctx, 'logic.cs-lock-public', 'error', lens, ln,
+            f'`lock({target})` —— {why}',
+            '用一个私有的专用锁对象：`private readonly object _gate = new();` 然后 `lock (_gate)`',
+            _unit_of(lens, ln))
+
+    # ── 静态 Random：它不是线程安全的，并发下会一起返回 0 ──
+    for f in lens.fields:
+        if 'static' not in f['modifiers']:
+            continue
+        base = f['type'].split('<')[0].strip()
+        if base == 'Random':
+            add(out, ctx, 'logic.cs-static-random', 'error', lens, f['line'],
+                f'`static Random {f["name"]}` —— Random 不是线程安全的，'
+                '多线程同时调用会破坏内部状态，典型症状是一起返回 0',
+                '.NET 6+ 直接用 `Random.Shared`（线程安全）；'
+                '旧版本用 `[ThreadStatic]` 或 ThreadLocal 各线程一份', f['owner'])
+
+    # ── Parse 不带 IFormatProvider：小数点在某些区域设置下是逗号 ──
+    for m in _RE_PARSE_NO_CULTURE.finditer(code):
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        if re.search(r'(CultureInfo|InvariantCulture|IFormatProvider)', line_txt):
+            continue
+        add(out, ctx, 'logic.cs-parse-no-culture', 'info', lens, ln,
+            f'`{m.group(1)}` 没有指定 IFormatProvider —— 会跟随当前线程的区域设置，'
+            '而在德语、法语等地区小数点是逗号，`"1.5"` 会解析成 15',
+            '解析机器数据（配置、接口、文件）一律传 `CultureInfo.InvariantCulture`；'
+            '只有面向用户输入时才用当前区域', _unit_of(lens, ln))
+
+
+# ── LINQ / EF Core / 资源 ──────────────────────────────────────────────────
+# 需要显式释放的类型：不进 using 就等异常路径上的泄漏
+_CS_DISPOSABLE = (
+    'FileStream', 'StreamReader', 'StreamWriter', 'MemoryStream', 'SqlConnection',
+    'SqlCommand', 'HttpResponseMessage', 'CancellationTokenSource', 'TransactionScope',
+    'BinaryReader', 'BinaryWriter', 'StringWriter', 'StringReader', 'Process',
+)
+_RE_NEW_DISPOSABLE = re.compile(
+    r'\b(?:var|[\w.<>]+)\s+(\w+)\s*=\s*new\s+(?:[\w.]+\.)?(' + '|'.join(_CS_DISPOSABLE) + r')\s*[({]')
+
+
+def check_csharp_linq_and_ef(lens, ctx, out, add):
+    """LINQ 的延迟执行、EF Core 的用法、以及需要释放的资源。"""
+    code = lens.code
+
+    # ── .Count() > 0：为了知道「有没有」，把整个序列数了一遍 ──
+    for m in _RE_COUNT_COMPARE.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.cs-count-vs-any', 'info', lens, ln,
+            '`.Count() > 0` 只是想知道「有没有元素」，却把整个序列完整遍历了一遍 —— '
+            '数据库查询上更糟：会真的发一条 COUNT 出去',
+            '用 `.Any()`：它拿到第一个元素就返回。判空则用 `!collection.Any()`',
+            _unit_of(lens, ln))
+
+    # ── 延迟查询被多次枚举：每一次都重新执行一遍（数据库上就是多发几条 SQL） ──
+    for m in _RE_LINQ_DEFERRED.finditer(code):
+        var = m.group(1)
+        tail = code[m.end():m.end() + 2500]
+        # _RE_ENUMERATE 是从 `.` 开始匹配的，所以 x.start() 之前的那一段以**变量名**结尾，
+        # 不是以点结尾——判据里多要一个 `\.` 就永远匹配不上，规则静默不响。
+        uses = [x for x in _RE_ENUMERATE.finditer(tail)
+                if re.search(rf'(?<![\w.]){re.escape(var)}\s*$', tail[:x.start()])]
+        # 只在「明确枚举两次以上」时才报——猜不准就不报
+        if len(uses) < 2:
+            continue
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.cs-linq-multiple-enumeration', 'warn', lens, ln,
+            f'`{var}` 是延迟执行的查询，后面被枚举了 {len(uses)} 次 —— '
+            '**每一次都会重新跑一遍**：内存集合是重复遍历，EF 查询则是重复发 SQL',
+            f'先物化一次：`var {var}List = {var}.ToList();`，之后都用它。'
+            '想保持延迟就确保只枚举一次', _unit_of(lens, ln))
+
+    # ── 需要释放的资源不用 using ──
+    for m in _RE_NEW_DISPOSABLE.finditer(code):
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        if re.search(r'\busing\b|\breturn\b', line_txt):
+            continue                      # using 声明/语句，或造出来交给调用方
+        u = lens.unit_at(ln)
+        if u and re.search(rf'\b{re.escape(m.group(1))}\s*\.\s*Dispose\s*\(', u.body):
+            continue                      # 显式 Dispose 了
+        add(out, ctx, 'logic.cs-disposable-no-using', 'warn', lens, ln,
+            f'`{m.group(2)}` 创建后没有 using —— 异常路径上不会被释放，'
+            '文件句柄、数据库连接、套接字都会一直占着',
+            f'写成 `using var {m.group(1)} = new {m.group(2)}(…);`（C# 8+ 的 using 声明），'
+            '或者用 `using (…) {{ … }}` 块', _unit_of(lens, ln))
+
+    # ── FromSqlRaw 拼接：参数被原样拼进 SQL ──
+    for m in _RE_SQL_RAW.finditer(code):
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        interpolated = bool(re.search(r'\$"', line_txt)) or bool(re.search(r'"\s*\+|\+\s*"', line_txt))
+        if not interpolated:
+            continue
+        add(out, ctx, 'logic.cs-sql-raw-concat', 'error', lens, ln,
+            f'`{m.group(1)}` 里拼接了变量 —— 参数被原样放进 SQL，这是注入入口',
+            '用参数化重载：`FromSqlRaw("… WHERE Id = {0}", id)`，'
+            '或者 `FromSqlInterpolated($"… WHERE Id = {id}")`（它会把插值转成参数，'
+            '注意与普通的 `$"..."` 拼接完全不同）', _unit_of(lens, ln))
+
+    # ── DbContext 注册成 Singleton：它不是线程安全的，还会一直持有变更跟踪 ──
+    for m in _RE_DI_SINGLETON.finditer(code):
+        types = m.group(1)
+        if not re.search(r'(DbContext|HttpClient)\b', types):
+            continue
+        ln = _line_of(lens, m.start())
+        what = 'DbContext' if 'DbContext' in types else 'HttpClient'
+        why = ('DbContext **不是线程安全的**，而且会一直攒着变更跟踪的实体，内存只增不减'
+               if what == 'DbContext' else
+               'HttpClient 应该用 IHttpClientFactory 管理，直接单例会拿不到 DNS 变更')
+        add(out, ctx, 'logic.cs-di-wrong-lifetime', 'error', lens, ln,
+            f'`{what}` 注册成了 Singleton —— {why}',
+            'DbContext 用 `AddDbContext`（默认 Scoped，每个请求一个）；'
+            'HttpClient 用 `AddHttpClient`', _unit_of(lens, ln))
+
+    # ── 循环里字符串拼接 ──
+    for u in lens.functions():
+        for lm in re.finditer(r'\b(?:foreach|for|while)\s*\([^)]*\)\s*\{', u.body):
+            blk = _block_after(u.body, lm.end() - 1)
+            hit = re.search(r'\b(\w+)\s*\+=\s*(?!\d)', blk)
+            if not hit:
+                continue
+            name = hit.group(1)
+            # 只在能确认它是 string 时才报：`sum += x` 这种数值累加是完全正常的写法
+            declared = rf'\bstring\s+{re.escape(name)}\b|\bvar\s+{re.escape(name)}\s*=\s*(?:""|string\.Empty)'
+            if not re.search(declared, u.body[:lm.start()]):
+                continue
+            ln = u.line_at(lm.start())
+            add(out, ctx, 'logic.cs-string-concat-loop', 'warn', lens, ln,
+                f'循环里对 string `{name}` 做 `+=` —— C# 的 string 是不可变的，'
+                '每次拼接都新建一个对象并复制全部内容，循环一多就是 O(n²)',
+                '循环外建 `StringBuilder`，循环里 `Append`，出循环 `ToString()`', u.label)
+
+    # ── 测试方法写成 async void：测试框架不会等它，断言失败也不会让用例变红 ──
+    if lens.is_test:
+        for u in lens.functions():
+            attrs = ' '.join(str(a) for a in u.decorators)
+            if not re.search(r'\[(Fact|Theory|Test|TestMethod|TestCase)', attrs):
+                continue
+            if 'async' in set(u.modifiers) and (u.ret_type or '').strip() == 'void':
+                add(out, ctx, 'test.cs-async-void-test', 'error', lens, u.start,
+                    f'测试 `{u.label}` 是 `async void` —— 测试框架拿不到 Task，'
+                    '**不会等它跑完**：断言还没执行用例就算通过了',
+                    '改成 `async Task`。这条特别隐蔽，因为用例会一直是绿的', u.label)
+
+
+# ── 与 dev-csharp「常见坑 TOP / DI 生命周期」对齐的几条 ────────────────────
+_RE_NEW_HTTPCLIENT = re.compile(r'\bnew\s+HttpClient\s*\(')
+_RE_CASE_COMPARE = re.compile(
+    r'\.\s*To(?:Lower|Upper)(?:Invariant)?\s*\(\s*\)\s*(?:==|!=|\.\s*Equals\s*\()'
+    r'|(?:==|!=)\s*\w+\s*\.\s*To(?:Lower|Upper)(?:Invariant)?\s*\(\s*\)')
+_RE_EVENT_SUB = re.compile(r'\b([\w.]+)\s*\+=\s*(?:new\s+\w+\s*\(\s*)?(\w+)\s*(?:\)\s*)?;')
+
+
+def check_csharp_pitfalls(lens, ctx, out, add):
+    """dev-csharp 技能里「评审必查」的那几条，改由机器每次都查。"""
+    code = lens.code
+
+    # ── 手 new HttpClient：长持会耗尽 socket，频繁 new 则 DNS 不刷新，两头都是坑 ──
+    for m in _RE_NEW_HTTPCLIENT.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.cs-new-httpclient', 'warn', lens, ln,
+            '直接 `new HttpClient()` —— 长期持有会耗尽 socket（连接处于 TIME_WAIT 不释放），'
+            '每次新建又拿不到 DNS 变更，两头都是坑',
+            '用 `IHttpClientFactory`（`services.AddHttpClient<T>()` 后注入 HttpClient），'
+            '它替你管理连接池与生命周期', _unit_of(lens, ln))
+
+    # ── ToLower() 之后比较：多分配一个字符串，还踩土耳其 i ──
+    for m in _RE_CASE_COMPARE.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.cs-case-compare', 'info', lens, ln,
+            '先 `ToLower()/ToUpper()` 再比较 —— 每次都多分配一个字符串，'
+            '而且在土耳其语区域 `I` 的小写不是 `i`，这类比较会得到意外结果',
+            '用 `string.Equals(a, b, StringComparison.OrdinalIgnoreCase)`。'
+            '文件名、协议头、标识符一律用 Ordinal 系列，别跟随区域设置', _unit_of(lens, ln))
+
+    # ── 订阅事件却没有对应的退订：长命对象订阅短命对象的事件 = 泄漏 ──
+    subscribed = {}
+    for m in _RE_EVENT_SUB.finditer(code):
+        target, handler = m.group(1), m.group(2)
+        if not re.search(r'(Changed|Click|Closed|Loaded|Received|Completed|Elapsed|Tick|Event)$',
+                         target.split('.')[-1]):
+            continue                      # 只认名字明确是事件的，`sum += x` 这类一律不碰
+        subscribed[(target, handler)] = _line_of(lens, m.start())
+    for (target, handler), ln in subscribed.items():
+        if re.search(rf'{re.escape(target)}\s*-=\s*', code):
+            continue
+        add(out, ctx, 'logic.cs-event-no-unsubscribe', 'warn', lens, ln,
+            f'订阅了事件 `{target} += {handler}` 但全文没有对应的 `-=` —— '
+            '事件源会一直持有订阅者的引用，订阅者永远不会被回收',
+            '在 Dispose / 页面卸载 / 组件销毁时 `-=` 退订；'
+            '订阅者比事件源短命时尤其要注意', _unit_of(lens, ln))

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

@@ -0,0 +1,201 @@
+# 代码自动修复：只修「改法唯一、不改变行为、不需要理解业务」的那几类。
+#
+# ── 这份清单为什么这么短 ──
+# 把「能标成自动修」的门槛放低，是这类工具最常见的坑：
+#
+#   `a == b` → `a === b`      看着安全，其实**会改变行为**："1" == 1 为真，"1" === 1 为假。
+#                             代码若正依赖松散比较，一键修完当场出故障。
+#   `count = count;` 删掉      看着无害，但它多半是「漏写了 this.」的现场证据。
+#                             删掉等于把 bug 的线索抹了，问题还在，只是再也查不到。
+#
+# 所以这两条都**不在**可修清单里——它们要报给人，由人判断。
+# 一个会自动改坏代码的修复器，比没有修复器危险得多：人会停止复核它的改动。
+#
+# 真正收进来的只有五类，共同点是「改完行为要么不变、要么是恢复本该有的行为」：
+#   test.only-left           删 .only —— 恢复「跑全部测试」这个本该有的行为
+#   readability.trailing-space 去行尾空白 —— 不进字符串内部，纯空白
+#   comment.commented-code   删被注释掉的死代码 —— 注释不参与执行
+#   structure.debug-left     删调试输出 —— 仅限单行、参数里没有函数调用的那种
+#   logic.empty-finally      删空 finally 块 —— 空块本就没有任何作用
+#
+# 默认 dry-run（只打印将要做的改动），加 --write 才落盘。
+
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import code_check as C   # noqa: E402
+import code_lens as L    # noqa: E402
+
+
+def _in_string(lens, lineno):
+    """这一行的行尾是否落在字符串字面量内部。
+
+    去行尾空白唯一会出事的地方就是多行字符串——模板串/三引号里的尾随空格
+    是**内容**，删了就改了程序的输出。掩码视图能精确判断这件事。
+    """
+    code_line = lens.code_line(lineno)
+    raw_line = lens.line(lineno)
+    # 掩码视图里该行尾部若被抹空而原文非空白，说明尾部在字符串/注释内
+    return len(code_line.rstrip()) < len(raw_line.rstrip()) and not raw_line.strip().startswith(('//', '#', '*'))
+
+
+# 单行、且参数里没有函数调用的调试输出才删——`console.log(compute())` 删掉会丢掉副作用
+_RE_SIMPLE_DEBUG = re.compile(
+    r'^\s*(?:console\.(?:log|debug|dir|trace)|System\.out\.print\w*|System\.err\.print\w*|print)'
+    r'\s*\([^()]*\)\s*;?\s*$')
+_RE_EMPTY_FINALLY = re.compile(r'\s*finally\s*\{\s*\}')
+
+
+def plan_fixes(lens, issues):
+    """把可修的问题翻译成具体的行编辑。
+
+    返回 [(lineno, new_text_or_None, rule, why)]；new_text 为 None 表示删除该行。
+    只规划不执行，便于 dry-run 先给人看。
+    """
+    edits = []
+    for it in issues:
+        if it.rule not in C.FIXABLE:
+            continue
+        ln = it.line
+        raw = lens.line(ln)
+
+        if it.rule == 'readability.trailing-space':
+            # 整文件一起处理（规则只报了第一处）
+            for i, text in enumerate(lens.lines, 1):
+                if text != text.rstrip() and not _in_string(lens, i):
+                    edits.append((i, text.rstrip(), it.rule, '去掉行尾空白'))
+            continue
+
+        if it.rule == 'test.only-left':
+            new = re.sub(r'\b(it|test|describe|context)\s*\.\s*only\s*\(', r'\1(', raw)
+            new = re.sub(r'\bfdescribe\s*\(', 'describe(', new)
+            new = re.sub(r'\bfit\s*\(', 'it(', new)
+            if new != raw:
+                edits.append((ln, new, it.rule, '删掉 .only，恢复跑全部用例'))
+            continue
+
+        if it.rule == 'structure.debug-left':
+            # 规则只报了首行，这里把该文件里所有「简单调试行」一起收掉
+            for i, text in enumerate(lens.lines, 1):
+                if _RE_SIMPLE_DEBUG.match(lens.code_line(i)) and text.strip():
+                    edits.append((i, None, it.rule, '删掉调试输出'))
+            continue
+
+        if it.rule == 'logic.empty-finally':
+            new = _RE_EMPTY_FINALLY.sub('', raw)
+            if new.strip():
+                edits.append((ln, new.rstrip(), it.rule, '删掉空 finally 块'))
+            else:
+                edits.append((ln, None, it.rule, '删掉空 finally 块'))
+            continue
+
+        if it.rule == 'comment.commented-code':
+            m = re.search(r'第 (\d+)–(\d+) 行', it.msg)
+            if not m:
+                continue
+            for i in range(int(m.group(1)), int(m.group(2)) + 1):
+                text = lens.line(i).strip()
+                if text.startswith(('//', '#')) or text.startswith('*'):
+                    edits.append((i, None, it.rule, '删掉被注释掉的死代码'))
+            continue
+    # 同一行只留一条编辑（删除优先），并按行号倒序——正序改会让后面的行号全部漂移
+    by_line = {}
+    for ln, new, rule, why in edits:
+        if ln not in by_line or new is None:
+            by_line[ln] = (ln, new, rule, why)
+    return sorted(by_line.values(), key=lambda x: -x[0])
+
+
+def apply_fixes(path, rules=None, write=False):
+    """对一个文件跑「体检 → 规划 → 应用 → 复检」的闭环。
+
+    复检是这里的重点：修完必须再体检一遍，断言这些规则真的消失了。
+    只做不验的修复器，会在某次正则改动后悄悄变成空转，而报告照样说「已修复 N 处」。
+    """
+    lens = L.read_lens(path)
+    issues, _, _ = C.check_files([path])
+    if rules:
+        issues = [i for i in issues if i.rule in set(rules)]
+    edits = plan_fixes(lens, issues)
+    if not edits:
+        return {'path': path, 'edits': [], 'changed': False, 'remaining': None}
+
+    lines = list(lens.lines)
+    for ln, new, _rule, _why in edits:            # 已按行号倒序
+        if not (1 <= ln <= len(lines)):
+            continue
+        if new is None:
+            del lines[ln - 1]
+        else:
+            lines[ln - 1] = new
+    new_text = '\n'.join(lines)
+
+    result = {
+        'path': path,
+        'edits': [{'line': ln, 'rule': r, 'why': w, 'action': '删除' if n is None else '改写',
+                   'before': lens.line(ln).strip()[:120], 'after': (n or '').strip()[:120]}
+                  for ln, n, r, w in sorted(edits, key=lambda x: x[0])],
+        'changed': new_text != lens.text,
+    }
+    # 复检：在**修改后的内容**上重新体检（不是在旧 lens 上），确认这些规则确实没了
+    fixed_rules = {r for _, _, r, _ in edits}
+    lens2 = L.read_lens(path, text=new_text)
+    issues2 = []
+    ctx = C.Ctx()
+    for fn in (C.check_logic, C.check_comment, C.check_readability,
+               C.check_structure, C.check_test, C.check_security):
+        fn(lens2, ctx, issues2)
+    still = sorted({i.rule for i in issues2} & fixed_rules)
+    result['remaining'] = still
+    result['parse_ok_after'] = lens2.parse_ok
+    if write and result['changed']:
+        if not lens2.parse_ok and lens.parse_ok:
+            # 修完反而解析不了了：绝不落盘。宁可不修，也不能交出一个更坏的文件。
+            result['aborted'] = '修改后文件无法解析，已放弃写入'
+            return result
+        with open(path, 'w', encoding='utf-8') as f:
+            f.write(new_text)
+        result['written'] = True
+    return result
+
+
+def main(argv):
+    import json
+    args = [a for a in argv if not a.startswith('--')]
+    flags = {a.split('=')[0]: (a.split('=', 1)[1] if '=' in a else True) for a in argv if a.startswith('--')}
+    target = args[0] if args else '.'
+    paths = L.walk_files(target) if os.path.isdir(target) else [target]
+    rules = flags['--rules'].split(',') if isinstance(flags.get('--rules'), str) else None
+    write = bool(flags.get('--write'))
+    results = [apply_fixes(p, rules, write) for p in paths]
+    results = [r for r in results if r['edits']]
+    if flags.get('--json'):
+        print(json.dumps({'write': write, 'files': results,
+                          'fixable_rules': sorted(C.FIXABLE)}, ensure_ascii=False))
+        return 0
+    if not results:
+        print('没有可自动修复的问题。\n'
+              '（可自动修的只有这几类：' + '、'.join(sorted(C.FIXABLE)) + '；\n'
+              '　其余问题——逻辑、注释与实现不符、缺测试、安全——都需要你自己判断怎么改。）')
+        return 0
+    total = sum(len(r['edits']) for r in results)
+    print(f'{"已修复" if write else "将修复"} {total} 处，涉及 {len(results)} 个文件'
+          + ('' if write else '（dry-run，加 --write 才真正落盘）'))
+    for r in results:
+        print(f'\n{r["path"]}')
+        for e in r['edits']:
+            print(f'  L{e["line"]} [{e["rule"]}] {e["why"]}')
+            print(f'     - {e["before"]}')
+            if e['action'] != '删除':
+                print(f'     + {e["after"]}')
+        if r.get('aborted'):
+            print(f'  ⚠ {r["aborted"]}')
+        elif r['remaining']:
+            print(f'  ⚠ 复检发现这些规则仍在响：{"、".join(r["remaining"])}（修复不完整，请人工确认）')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))