chore: 引入 async def 同步阻塞静态检查 + 修复存量违规 (Project-N-E-K-O#842)

* chore: 引入 async def 同步阻塞静态检查 + 修复存量违规

动机：主进程运行 FastAPI + asyncio 事件循环，心跳和 WebSocket 对
事件循环 stall 极其敏感（曾出现 end_session 清理期间 ~1s 阻塞）。
仅靠人工 grep 无法阻止同步阻塞调用反复潜入，需要静态守卫。

实现：
- 启用 ruff 的 ASYNC210/220/221/222/251 规则，覆盖 time.sleep /
  requests / urllib.request / subprocess.run / Popen.wait 等。
- 新增 scripts/check_async_blocking.py，用 AST 补齐 ruff 不覆盖的
  部分：Thread/Process.join(timeout=) / queue.Queue.get() /
  原生 socket.recv/accept/connect。
  接收者匹配用 tail-name（"tts_thread" / "request_queue" / "sock"…）
  以避免 httpx / websockets / zmq socket 的误报。
  嵌套 sync def 不会被检查——匹配 ruff 的行为，让放进线程/executor
  的 worker 天然免于误报。
- 新增 .github/workflows/analyze.yml，CI 并行跑 ruff 与自定义脚本。
- 支持 `# noqa: ASYNC_BLOCK — <原因>` 行级抑制。

修复存量违规：
- main_server.py:546/596 initialize_character_data 两处
  sync_process[k].join(timeout=...) 包裹进 asyncio.to_thread。
- main_logic/core.py:1453 tts_thread.join(timeout=1.0) 同上。
- main_logic/cross_server.py:174 maintain_connection 内
  message_queue.get() 改为 get_nowait()，和外层 empty() 检查匹配，
  消除竞态。

验证：ruff check . 与 scripts/check_async_blocking.py 均通过；
合成违规（time.sleep / Thread.join / Queue.get / socket.recv /
requests.get / subprocess.run）均被其中一个工具拦截。

https://claude.ai/code/session_01TC7MP5nYYtXZXMmTMWNQuN

* chore(ci): analyze.yml 显式收敛 GITHUB_TOKEN 至 contents:read

静态检查 job 不需要写入 repo 或任何其他资源，按最小权限原则显式
声明 permissions，避免默认宽权限。

https://claude.ai/code/session_01TC7MP5nYYtXZXMmTMWNQuN

* refactor(async-check): 精确捕获 Empty + 澄清 plugin/ 为何不进默认扫描

- cross_server.py: `except Exception` 收紧为 `except Empty`（CodeRabbit
  建议喵）。语义更清晰，`queue.Queue.get_nowait()` 空队列就是 Empty，
  其他异常不该在这里被吞。
- check_async_blocking.py: 在 DEFAULT_PATHS 旁加注释说明为什么不把
  `plugin/` 纳入默认扫描——pyzmq Socket 和 asyncio.Queue 的 tail-name
  与本检查器的启发式冲撞，在 plugin/ 下会产生 15+ 条误报（zmq
  `sock.recv`/`connect`、`await asyncio.wait_for(q.get(), ...)` 等）。
  ruff 的 ASYNC* 规则已经覆盖 plugin/，后续可以单独用类型推断的方式
  再把 plugin/ 纳入这个脚本。

https://claude.ai/code/session_01TC7MP5nYYtXZXMmTMWNQuN

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: wehos

.github/workflows/analyze.yml

@@ -0,0 +1,42 @@
+name: Analyze
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+# Static-check job only needs to read the checked-out source.
+permissions:
+  contents: read
+
+jobs:
+  python-lint:
+    name: Python lint (ruff + async-blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install ruff
+        # ruff is the only dev dep we need for the lint job; a full uv sync
+        # pulls heavy native extensions (playwright, numpy, etc.) that are
+        # unnecessary for static checks.
+        run: uv tool install ruff==0.15.4
+
+      - name: ruff check (incl. ASYNC210/220/221/222/251)
+        run: ruff check .
+
+      - name: Forbid blocking calls in async def bodies
+        # Custom AST checker — covers the gaps flake8-async doesn't:
+        # Thread/Process.join, queue.Queue.get, raw socket recv/accept/connect.
+        run: python scripts/check_async_blocking.py

main_logic/core.py

@@ -1450,7 +1450,7 @@ async def start_session(self, websocket: WebSocket, new=False, input_mode='audio
                 logger.info("当前模式不需要TTS，关闭TTS线程")
                 try:
                     self.tts_request_queue.put(("__shutdown__", None))  # 通知线程退出
-                    self.tts_thread.join(timeout=1.0)  # 等待线程结束
+                    await asyncio.to_thread(self.tts_thread.join, 1.0)  # 等待线程结束
                 except Exception as e:
                     logger.error(f"关闭TTS线程时出错: {e}")
                 finally:

main_logic/cross_server.py

@@ -13,6 +13,7 @@
 import time
 import pickle
 import aiohttp
+from queue import Empty
 from config import MONITOR_SERVER_PORT, MEMORY_SERVER_PORT, COMMENTER_SERVER_PORT
 from datetime import datetime
 import json
@@ -171,7 +172,10 @@ async def maintain_connection(chat_history, lanlan_name):
             try:
                 # 检查消息队列
                 while not message_queue.empty():
-                    message = message_queue.get()
+                    try:
+                        message = message_queue.get_nowait()
+                    except Empty:
+                        break
 
                     if message["type"] == "json":
                         # Forward to monitor if enabled

plugin/plugins/mijia/__init__.py

@@ -150,19 +150,24 @@ async def _save_credential(self, credential: Credential):
         if sys.platform == "win32":
             try:
                 import subprocess
-                username = subprocess.check_output(
-                    ["cmd", "/c", "echo", "%USERNAME%"], text=True
-                ).strip()
-                path_str = str(self.credential_path)
-                # 先移除所有继承权限，再授权当前用户完全控制
-                result = subprocess.run(
-                    ["icacls", path_str, "/inheritance:r", "/grant:r", f"{username}:F"],
-                    check=False, capture_output=True, text=True
-                )
-                if result.returncode != 0:
+
+                def _apply_windows_acl() -> tuple[int, str]:
+                    username = subprocess.check_output(
+                        ["cmd", "/c", "echo", "%USERNAME%"], text=True
+                    ).strip()
+                    path_str = str(self.credential_path)
+                    # 先移除所有继承权限，再授权当前用户完全控制
+                    result = subprocess.run(
+                        ["icacls", path_str, "/inheritance:r", "/grant:r", f"{username}:F"],
+                        check=False, capture_output=True, text=True
+                    )
+                    return result.returncode, (result.stderr or "").strip()
+
+                returncode, stderr = await asyncio.to_thread(_apply_windows_acl)
+                if returncode != 0:
                     self.logger.warning(
-                        f"设置凭据文件权限失败(Windows): icacls 返回码 {result.returncode}"
-                        + (f", stderr: {result.stderr.strip()}" if result.stderr.strip() else "")
+                        f"设置凭据文件权限失败(Windows): icacls 返回码 {returncode}"
+                        + (f", stderr: {stderr}" if stderr else "")
                     )
                 else:
                     self.logger.debug("凭据文件权限已设置（仅当前用户）")

pyproject.toml

@@ -106,3 +106,27 @@ dev = [
     "ruff>=0.15.4",
 ]
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Ruff: enforce zero-blocking-call policy in async def bodies.
+# Covers: time.sleep / requests / urllib.request / subprocess.* (run, Popen…).
+# Gaps (threading.Thread.join timeout, queue.Queue.get, threading.Event.wait
+# timeout, raw socket.recv/send/accept/connect) are caught by the companion
+# script scripts/check_async_blocking.py which the CI Analyze job also runs.
+# ─────────────────────────────────────────────────────────────────────────────
+[tool.ruff]
+target-version = "py311"
+extend-exclude = [
+  "frontend",
+  "dist",
+  ".venv",
+]
+
+[tool.ruff.lint]
+select = [
+  "ASYNC210",  # blocking HTTP call (requests / urllib / httpx.Client)
+  "ASYNC220",  # create-subprocess (Popen) in async function
+  "ASYNC221",  # subprocess.run / call / check_output / check_call
+  "ASYNC222",  # Popen.wait / Popen.communicate
+  "ASYNC251",  # time.sleep in async function
+]
+