labull-framework 0.1.0__py3-none-any.whl

labull_framework/magic_block/validate.py

@@ -0,0 +1,558 @@
+"""
+"什么代码能入库"的**唯一判据**：包结构 / 清单 / 文件名 / 前端脚本，以及块后端的 `ast` 静态判据
+与**子进程试加载**。保存（`service.save`）与体检（`health.evaluate`）都只调这里 —— 判据写两处必然漂，
+而"保存说合法、体检说非法"是最难查的一类事故。
+
+🔴 试加载在**子进程**里：那份代码是使用者写的，顶层死循环 / 主动 `os._exit` 会带走整个服务进程。
+   超时（10 秒）**不算通过** —— "不知道"不等于"没问题"。
+🔴 这里判的**只是库里的数据**（这一包要不要存进去），不是使用者的项目代码。
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from .sdk import BLOCK_BACKEND_FILE, BLOCK_ENTRY, BLOCK_MANIFEST, LIB_SDK
+
+# ──────────────────────────── 包结构与清单的判据 ────────────────────────────
+
+#: 清单只认这四个键，全部必填（顺序就是文档里的顺序）。
+MANIFEST_KEYS: tuple[str, ...] = ('id', 'module', 'name', 'brief')
+
+#: 包里文件名的合法形状：只许字母数字与 `. _ - /`；不许绝对路径、不许 `..` 段。
+FILE_NAME_PATTERN = re.compile(r'^(?!/)(?![A-Za-z]:)[A-Za-z0-9._\-/]+$')
+
+#: 可读名（清单里的 `name`）：允许中文，但不许空、不超 40 字符、不含控制字符。
+NAME_MAX = 40
+NAME_PATTERN = re.compile(r'^(?=[\s\S]*\S)[^\u0000-\u001f\u007f]{1,40}$')
+
+#: 清单里 `id` 的形状：uuid（8-4-4-4-12）。
+BLOCK_ID_PATTERN = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.I)
+
+#: 清单里 `module` 的形状。🔴 它同时是 Django 的 app label（`INSTALLED_APPS` 里那一段），
+#:    所以只许小写字母数字、必须以字母开头 —— 横线与下划线在那里当不了标识符。
+MODULE_PATTERN = re.compile(r'^[a-z][a-z0-9]*$')
+
+#: 清单里的键名形状。
+MANIFEST_KEY_PATTERN = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
+
+# ──────────────────────────── 块后端的 ast 判据 ────────────────────────────
+#
+# 🔴 **块里的 import 不做任何检查**：这个 Django 项目里能 import 的，块里就能 import。
+#    没有白名单、没有禁止清单 —— 那种清单要么漏、要么挡住正常写法（`from django.utils import timezone`
+#    这种写法凭什么不许？），而且它维护的是一份永远不完整的模块名单。
+# 🔴 **只有 `import` 才是真的关联**：块里写了什么，就在这个块被加载时才真的加载它。
+# ⚠️ **唯一还隔着的一层是配置**：环境变量里只有带 `BLOCK_` 前缀的能进 `ctx.config`（见 `dispatch`）。
+# 🔴 **这不是安全沙箱**：`backend_open.py` 是管理员写进库里的数据。下面这些 `ast` 判据要的是
+#    "这包能不能被分发器正确执行"（有没有那条 SDK import、方法与装饰器形状对不对），
+#    以及"模块级别在加载时就动数据"；试加载（`trial_load`）负责把拼错的模块名 / 语法错当场报出来。
+
+#: 那条 SDK import 里能取的名字（就这两个）。
+SDK_NAMES: tuple[str, ...] = ('MagicBackendAPI', 'errors')
+
+#: 🔴 唯一还拦的两个内置：它们在块里**造出新的代码**（于是"这份正文长什么样"就不再是全部事实）。
+#: 别的调用一律不拦 —— 块后端与项目里别的 Python 代码没有区别。
+_NO_DYNAMIC_CODE: frozenset[str] = frozenset({'eval', 'exec'})
+
+#: 试加载的子进程超时（秒）。判据就是这个数。
+TRIAL_LOAD_TIMEOUT = 10
+
+#: 试加载脚本：真的 import 那份 SDK 模块、把块正文当模块执行一次。
+#: 🔴 块正文走**环境变量里的 JSON**，不往脚本里拼字符串（正文里一个引号就能把脚本本身改坏）。
+#: ⚠️ 这里**不做任何替身**：块 import 什么就真的 import 什么 —— 块能用的东西与项目里别的代码一模一样。
+_TRIAL_SCRIPT = (
+    'import json, os, sys\n'
+    'SOURCE = json.loads(os.environ["LABULL_TRIAL_SOURCE"])\n'
+    'try:\n'
+    '    exec(compile(SOURCE, "backend_open.py", "exec"), {"__name__": "backend_open"})\n'
+    'except Exception as exc:\n'
+    '    sys.stderr.write(f"{type(exc).__name__}: {exc}")\n'
+    '    sys.exit(1)\n'
+)
+
+
+# ──────────────────────────── 清单（零依赖手写解析） ────────────────────────────
+
+
+def _strip_comment(line: str) -> str:
+    """去掉一行里的注释：`#` 之后是注释，但**引号内**的 `#` 是正文（`name: 'a # b'`）。"""
+    quote = ''
+    for index, char in enumerate(line):
+        if quote:
+            if char == quote:
+                quote = ''
+        elif char in ('"', "'"):
+            quote = char
+        elif char == '#':
+            return line[:index]
+    return line
+
+
+def _separator_at(line: str) -> int:
+    """第一个**不在引号里**的 `:`（「键: 值」的分隔符）；没有就回 -1。"""
+    quote = ''
+    for index, char in enumerate(line):
+        if quote:
+            if char == quote:
+                quote = ''
+        elif char in ('"', "'"):
+            quote = char
+        elif char == ':':
+            return index
+    return -1
+
+
+def _unquote(value: str) -> str:
+    """去掉值两侧**成对**的引号；不成对的原样留着，让后面的判据说它不合法。"""
+    if not value or value[0] not in ('"', "'"):
+        return value
+    if len(value) >= 2 and value[-1] == value[0]:
+        return value[1:-1].strip()
+    return value
+
+
+def _now_in(files: dict[str, str]) -> str:
+    """包里现在有哪些文件（写进报文：缺了什么、手上有什么，一眼看得出）。"""
+    names = list(files)
+    return f'现在包里有：{" / ".join(names)}' if names else '现在这个包是空的'
+
+
+def parse_manifest(text: str) -> tuple[dict[str, str], list[str]]:
+    """解析清单正文：`(认得的字段, 逐条问题)`。
+
+    🔴 不引 YAML 库：校验器跑在保存路径上，多一个依赖就多一处"装不上就存不了"。
+    🔴 不认识的写法（列表 / 嵌套 / 没有冒号 / 不认识的键 / 重复键）**各报一条**，绝不静默忽略 ——
+       静默的后果是"块没有身份"这种错要到运行期才现形。
+    """
+    issues: list[str] = []
+    found: dict[str, str] = {}
+    seen_at: dict[str, int] = {}
+
+    for index, raw in enumerate(text.splitlines()):
+        line_no = index + 1
+        line = _strip_comment(raw).strip()
+        if not line:
+            continue
+        if line.startswith('-'):
+            issues.append(
+                f'第 {line_no} 行是列表写法（{line!r}）：清单只认「键: 值」，四个键各占一行 —— '
+                '例如 name: 客户档案'
+            )
+            continue
+        at = _separator_at(line)
+        if at < 0:
+            issues.append(
+                f'第 {line_no} 行不是「键: 值」（{line!r}）：清单只认「键: 值」与 # 注释 —— '
+                '要么删掉这一行，要么照 name: 客户档案 写'
+            )
+            continue
+        key = line[:at].strip()
+        if not MANIFEST_KEY_PATTERN.match(key):
+            issues.append(
+                f'第 {line_no} 行的键名不合法（{key!r}）：键名只许字母或下划线开头，'
+                f'认得的键只有 {" / ".join(MANIFEST_KEYS)}'
+            )
+            continue
+        if key not in MANIFEST_KEYS:
+            issues.append(
+                f'第 {line_no} 行的键不认识（{key}）：清单只有 {" / ".join(MANIFEST_KEYS)} 这四个键'
+            )
+            continue
+        if key in seen_at:
+            issues.append(f'第 {line_no} 行重复写了 {key}（第 {seen_at[key]} 行已经写过）：一个键只许出现一次')
+            continue
+        seen_at[key] = line_no
+        found[key] = _unquote(line[at + 1:].strip())
+
+    hints = {
+        'id': '块的 uuid，必须与页面里挂载它时写死的那个 uuid 逐字一致',
+        'module': '模块名（小写字母与数字，必须以字母开头），例如 home',
+        'name': f'可读名：可以用中文，不超过 {NAME_MAX} 个字符',
+        'brief': '一句话说明这个块解决什么问题',
+    }
+    for key in MANIFEST_KEYS:
+        value = found.get(key)
+        if value is None or value == '':
+            issues.append(f'清单里缺少 {key}（或者是空的）：{hints[key]}')
+            continue
+        if key == 'id' and not BLOCK_ID_PATTERN.match(value):
+            issues.append(f'清单里的 id 不是 uuid：{value!r} —— 要 8-4-4-4-12 那种十六进制')
+        elif key == 'module' and not MODULE_PATTERN.match(value):
+            issues.append(
+                f'清单里的 module 不合法：{value!r} —— 它同时是 Django 的 app label，'
+                '所以只许小写字母与数字、必须以字母开头（不能有横线与下划线），例如 home / orders'
+            )
+        elif key == 'name' and not NAME_PATTERN.match(value):
+            issues.append(
+                f'清单里的 name 不合法：{value!r} —— 不能超过 {NAME_MAX} 个字符、不能含控制字符（中文可以）'
+            )
+    return found, issues
+
+
+def read_manifest(files: dict[str, str]) -> tuple[dict[str, str] | None, list[str]]:
+    """从包读清单：**齐备且合法**才给 manifest，否则 `None` + 逐条问题。
+
+    🔴 清单缺失 / 为空也在这里报（它是必备件，调用方不必自己再判一次）。
+    """
+    if BLOCK_MANIFEST not in files:
+        return None, [f'包里缺清单：必须有 {BLOCK_MANIFEST}（{_now_in(files)}）']
+    text = files.get(BLOCK_MANIFEST) or ''
+    if not text.strip():
+        return None, [f'{BLOCK_MANIFEST} 不能是空文件']
+    manifest, issues = parse_manifest(text)
+    if issues:
+        return None, issues
+    return manifest, []
+
+
+def _valid_file_name(name: str) -> bool:
+    """包内文件名合法吗（形状 + 不许 `..` 段）。"""
+    return bool(FILE_NAME_PATTERN.match(name)) and '..' not in str(name).split('/')
+
+
+def check_files(files: dict[str, str]) -> list[tuple[str, str]]:
+    """包结构那一半：入口在不在、清单读不读得出、文件名许不许、有没有动态执行。
+
+    返回 `[(stage, issue)]`：stage 走 `health` 落库时要用（见 `health.CHECKS`）。
+    """
+    out: list[tuple[str, str]] = []
+    if BLOCK_ENTRY not in files:
+        out.append(('files', f'包里缺入口：必须有 {BLOCK_ENTRY}（{_now_in(files)}）'))
+    elif not (files.get(BLOCK_ENTRY) or '').strip():
+        out.append(('files', f'{BLOCK_ENTRY} 不能是空文件'))
+    for message in read_manifest(files)[1]:
+        out.append(('files', message))
+    for name in files:
+        if not _valid_file_name(name):
+            out.append(('files', f'文件名不合法：{name!r}（只许字母数字与 . _ - /，且不许 .. 与绝对路径）'))
+    # 🔴 到此为止：块前端那些文件（`.html` / `.js` / `.css`）的正文一个字都不看 ——
+    #    前端代码合不合格是作者与前端那一侧的事，服务端保存时只判"这包能不能跑"。
+    return out
+
+
+# ──────────────────────────── 块后端的静态判据 ────────────────────────────
+
+
+def _line_of(node: ast.AST) -> int:
+    """这个节点在第几行（报文要能对上编辑器里的行号）。"""
+    return getattr(node, 'lineno', 0) or 0
+
+
+def _banned_call(node: ast.AST) -> str:
+    """这一处调用命中了哪条禁令（没命中回空串）。
+
+    🔴 **只拦"在块里制造代码"的那两个内置**（`eval` / `exec`）。别的调用一概不拦 ——
+       块后端与项目里别的 Python 代码没有区别：`from django.utils import timezone`、
+       `Order.objects.filter(...)`、`requests.get(...)` 全是正常写法。
+       "哪些模块不许 import"那种名单已经不做了（见文件头）。
+    ⚠️ 只认**调用**：读一个属性没有副作用，报了只会是假错。
+    """
+    if isinstance(node, ast.Name) and node.id in _NO_DYNAMIC_CODE:
+        return node.id
+    return ''
+
+
+def _has_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """这个方法上挂了 `@MagicBackendAPI`（带不带参数都算）吗。"""
+    for decorator in node.decorator_list:
+        target = decorator.func if isinstance(decorator, ast.Call) else decorator
+        if isinstance(target, ast.Name) and target.id == 'MagicBackendAPI':
+            return True
+    return False
+
+
+def _method_issues(file: str, cls: ast.ClassDef, node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]:
+    """一个方法的判据：带装饰器、是同步的、签名是 `(self, ctx, params)`；`__init__` 里不许有调用。"""
+    issues: list[str] = []
+    where = f'{file} 第 {_line_of(node)} 行（{cls.name}.{node.name}）'
+
+    if isinstance(node, ast.AsyncFunctionDef):
+        issues.append(f'{where}：不要写成 async def —— 分发器按同步调用它，异步只会回一个协程对象')
+    if not _has_decorator(node):
+        issues.append(f'{where}：没有 @MagicBackendAPI，所以它**不是路由**（路径从装饰器来，不是从"是 public 方法"来）')
+
+    if node.name == '__init__':
+        for child in ast.walk(node):
+            if isinstance(child, ast.Call):
+                issues.append(f'{where}：__init__ 里不许有任何调用（它只用来赋常量，副作用会在加载时发生）')
+                break
+        return issues
+
+    args = node.args
+    positional = [*args.posonlyargs, *args.args]
+    if args.vararg or args.kwarg:
+        issues.append(f'{where}：签名不要写 *args / **kwargs（参数就是 ctx 与 params 两个）')
+    if len(positional) != 3:
+        issues.append(
+            f'{where}：签名要写成 def {node.name}(self, ctx, params) —— 就两个参数'
+            f'（ctx 与 params），现在读到 {max(len(positional) - 1, 0)} 个'
+        )
+    elif args.defaults or args.kwonlyargs:
+        issues.append(f'{where}：参数不许带默认值、不许有关键字参数（就 self, ctx, params）')
+    return issues
+
+
+def check_backend(src: str) -> list[tuple[str, str]]:
+    """块后端正文的 `ast` 判据 + 子进程试加载。返回 `[(stage, issue)]`。
+
+    判据顺序（也就是报文顺序）：模块级语句形状 → import 形状与那条 SDK import → 类体与方法 →
+    危险调用（整棵树扫） → 试加载（前面都过了才跑）。
+
+    🔴 **不看 import 的是哪个模块**（见本文件头部）：项目里能 import 的，块里就能 import。
+    """
+    file = BLOCK_BACKEND_FILE
+    if not str(src or '').strip():
+        return [('backend', f'{file} 不能是空文件（要么不写这个文件，要么写一个类）')]
+
+    try:
+        tree = ast.parse(src, filename=file)
+    except SyntaxError as exc:
+        return [('syntax', f'{file} 第 {exc.lineno or 0} 行第 {exc.offset or 0} 列有语法错：{exc.msg}')]
+
+    issues: list[tuple[str, str]] = []
+
+    # ① 模块级只许 import / class / __all__ / docstring。
+    #    🔴 `ast.Expr` 必须**显式分叉成"只许字符串常量"**：整体放行 `Expr` 就是漏洞 ——
+    #       任何调用都是 `Expr`，而那段代码会在**别人的进程**里执行。
+    for node in tree.body:
+        if isinstance(node, ast.Expr):
+            if isinstance(node.value, ast.Constant) and isinstance(node.value.value, str):
+                continue
+            issues.append(
+                (
+                    'backend',
+                    f'{file} 第 {_line_of(node)} 行：模块级只许 import / class / docstring / __all__ —— '
+                    '这一行是一个表达式，它会在加载这个块时真的执行；要写逻辑请写进类的方法里',
+                )
+            )
+            continue
+        if isinstance(node, ast.Assign):
+            if [t.id for t in node.targets if isinstance(t, ast.Name)] == ['__all__']:
+                continue
+            issues.append(
+                (
+                    'backend',
+                    f'{file} 第 {_line_of(node)} 行：模块级不许赋值 / 不许调用（只有 __all__ 例外）—— '
+                    '模块级副作用会在保存试加载时就动到数据',
+                )
+            )
+            continue
+        if not isinstance(node, (ast.Import, ast.ImportFrom, ast.ClassDef)):
+            issues.append(
+                (
+                    'backend',
+                    f'{file} 第 {_line_of(node)} 行：模块级只许 import / class / docstring / __all__ —— '
+                    '要写逻辑请写进类的方法里',
+                )
+            )
+
+    # ② import 的**形状**（不看模块名）：那条 SDK import 必须在、只许一条、不许 `as` 改名。
+    imports = [node for node in tree.body if isinstance(node, (ast.Import, ast.ImportFrom))]
+    sdk_lines = [node for node in imports if isinstance(node, ast.ImportFrom) and (node.module or '') == LIB_SDK]
+    if not sdk_lines:
+        issues.append(
+            ('backend', f'{file} 里必须有一条 from {LIB_SDK} import MagicBackendAPI —— 没有它就没有任何接口')
+        )
+    if len(sdk_lines) > 1:
+        lines = ' / '.join(str(_line_of(node)) for node in sdk_lines)
+        issues.append(
+            (
+                'backend',
+                f'{file} 第 {_line_of(sdk_lines[1])} 行：那条 SDK import 只许写**一条**（现在有 '
+                f'{len(sdk_lines)} 条，第 {lines} 行）—— 要别的名字就并进同一条',
+            )
+        )
+    for node in imports:
+        for alias in node.names:
+            if alias.asname:
+                issues.append(
+                    (
+                        'backend',
+                        f'{file} 第 {_line_of(node)} 行：import 不许 as 改名（收到的是 '
+                        f'{alias.name} as {alias.asname}）—— 名字与契约逐字对应，改名等于把代码改坏',
+                    )
+                )
+    for node in sdk_lines:
+        for alias in node.names:
+            if alias.name not in SDK_NAMES:
+                issues.append(
+                    (
+                        'backend',
+                        f'{file} 第 {_line_of(node)} 行：SDK 里没有 {alias.name} —— '
+                        f'能 import 的只有 {" / ".join(SDK_NAMES)}',
+                    )
+                )
+
+    # ③ 类体只许方法；方法逐条判。
+    classes = [node for node in tree.body if isinstance(node, ast.ClassDef)]
+    if not classes:
+        issues.append(
+            (
+                'backend',
+                f'{file} 里必须有一个类（类名 + 方法名 = 路由名，例如 Customer.create）—— '
+                '模块级函数认不出来',
+            )
+        )
+    for cls in classes:
+        for node in cls.body:
+            if isinstance(node, ast.Expr):
+                if isinstance(node.value, ast.Constant) and isinstance(node.value.value, str):
+                    continue
+                issues.append(
+                    (
+                        'backend',
+                        f'{file} 第 {_line_of(node)} 行（类 {cls.name} 里）：类体里只许写方法 —— '
+                        '这一行是表达式，它会在类定义时执行',
+                    )
+                )
+                continue
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                for message in _method_issues(file, cls, node):
+                    issues.append(('backend', message))
+                continue
+            issues.append(
+                (
+                    'backend',
+                    f'{file} 第 {_line_of(node)} 行（类 {cls.name} 里）：类体里只许写方法'
+                    '（不许类变量、不许嵌套类）—— 常量写在方法里',
+                )
+            )
+
+    # ④ 在块里造代码的那两个内置（`eval` / `exec`）：整棵树扫一遍（不只是方法体）。
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            hit = _banned_call(node.func)
+            if hit:
+                issues.append(
+                    (
+                        'backend',
+                        f'{file} 第 {_line_of(node)} 行：不许调用 {hit} —— '
+                        '块代码是运行时加载的数据，不要在块里再拼一段代码出来',
+                    )
+                )
+
+    # ⑤ 前面都过了才真的加载一次（装饰器求值会不会炸，只有跑一遍才知道）。
+    if not issues:
+        for message in trial_load(src):
+            issues.append(('backend', message))
+    return issues
+
+
+def trial_load(src: str) -> list[str]:
+    """在子进程里把这份块后端加载一次（顶层 + 装饰器求值，handler 一次都不调）。
+
+    🔴 超时（10 秒）**不算通过**：那是"不知道"，不是"没问题"。
+    🔴 这条判据的价值在**及时报错**：块里 `import` 了一个项目里没装的包、拼错了模块名、
+       装饰器参数写错 —— 都在保存那一刻报出来，而不是等到某次请求炸。
+    """
+    env = dict(os.environ)
+    # 🔴 把父进程的 sys.path 交过去：子进程默认的 path 里没有项目根，
+    #    不交的话每个块都会报"找不到 labull_framework / modules"——那是假错。
+    env['PYTHONPATH'] = os.pathsep.join(item for item in sys.path if item)
+    env['LABULL_TRIAL_SOURCE'] = json.dumps(src, ensure_ascii=False)
+    try:
+        done = subprocess.run(
+            [sys.executable, '-c', _TRIAL_SCRIPT],
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=TRIAL_LOAD_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        return [f'{BLOCK_BACKEND_FILE} 试加载超过 {TRIAL_LOAD_TIMEOUT} 秒没有结束，已中止（顶层不许做耗时的事）']
+    except OSError as exc:
+        return [f'{BLOCK_BACKEND_FILE} 试加载跑不起来（{exc}）：找不到可用的 Python 解释器']
+
+    if done.returncode == 0:
+        return []
+    lines = (done.stderr or '').strip().splitlines()
+    return [f'{BLOCK_BACKEND_FILE} 加载失败（顶层与装饰器不许出错）：{lines[-1] if lines else done.returncode}']
+
+
+# ──────────────────────────── 路由名（唯一一处扫它） ────────────────────────────
+
+
+def _tree_of(src: str) -> ast.Module | None:
+    """把块后端正文解析成语法树（空 / 语法错 ⇒ `None`，由 `check_backend` 去报那一条）。"""
+    if not str(src or '').strip():
+        return None
+    try:
+        return ast.parse(str(src), filename=BLOCK_BACKEND_FILE)
+    except SyntaxError:
+        return None
+
+
+def routes_of(src: str) -> list[str]:
+    """从 `ast` 读出的 `类名.方法名` 列表（**不执行任何代码**）。
+
+    🔴 这是**唯一一处**扫路由名的地方：保存校验的引用判据、`api.open.d.ts` 的正文、
+       以及运行期那张真实路由表（`registry.py`）都以此为准。
+    """
+    tree = _tree_of(src)
+    if tree is None:
+        return []
+    out: list[str] = []
+    for cls in [node for node in tree.body if isinstance(node, ast.ClassDef)]:
+        for node in cls.body:
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if _has_decorator(node):
+                out.append(f'{cls.name}.{node.name}')
+    return out
+
+
+def routes_meta_of(src: str) -> dict[str, str]:
+    """`类名.方法名` → 声明的权限（读 `@MagicBackendAPI(permission=…)`）。
+
+    ⚠️ 只认字符串字面量；省略 / 算出来的值一律记成空串（= 只要登录）。
+    """
+    tree = _tree_of(src)
+    if tree is None:
+        return {}
+    out: dict[str, str] = {}
+    for cls in [node for node in tree.body if isinstance(node, ast.ClassDef)]:
+        for node in cls.body:
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if not _has_decorator(node):
+                continue
+            permission = ''
+            for decorator in node.decorator_list:
+                if not isinstance(decorator, ast.Call):
+                    continue
+                target = decorator.func
+                if not (isinstance(target, ast.Name) and target.id == 'MagicBackendAPI'):
+                    continue
+                for keyword in decorator.keywords:
+                    if keyword.arg == 'permission' and isinstance(keyword.value, ast.Constant):
+                        value = keyword.value.value
+                        permission = value if isinstance(value, str) else ''
+            out[f'{cls.name}.{node.name}'] = permission
+    return out
+
+
+# ──────────────────────────── 调用方要的那几件 ────────────────────────────
+
+
+def check_block(files: dict[str, str]) -> list[tuple[str, str]]:
+    """一整个块包的判据：包结构 + **块后端**。返回 `[(stage, issue)]`。
+
+    🔴 **只校验服务端那一半**：块的前端代码是作者自己的东西，保存时一个字都不看 ——
+       前端该不该合格由前端自己负责（它的编辑器 / 控制台那一侧）。
+    """
+    files = files or {}
+    src = files.get(BLOCK_BACKEND_FILE)
+    out = check_files(files)
+    if src is not None:
+        if not isinstance(src, str):
+            out.append(('backend', f'{BLOCK_BACKEND_FILE} 的正文必须是文本'))
+        else:
+            out.extend(check_backend(src))
+    return out
+