labull-framework 0.1.0__py3-none-any.whl

labull_framework/magic_block/export.py

@@ -0,0 +1,773 @@
+"""magic block export：**把库里的块算成一整个开发包**，以及**把改好的目录读回库**。
+
+四个函数，三个方向，都是"块作者用自己编辑器改代码"那条路：
+
+| 方向 | 函数 | 干什么 |
+|---|---|---|
+| 出 | `export_package()` | 库 → **一份"相对路径 → 正文"的表**（浏览器把它写进用户选的目录） |
+| 回 | `scan_folders(upload)` | **浏览器扫到的**目录 → 逐块对比（只读，不写库） |
+| 回 | `read_dir(path)` | **服务器上的**目录 → 逐块对比（同一套判据；CLI 或源码就在服务器上时用） |
+| 回 | `write_dir(items, actor)` | 把勾选的块写回库（**走保存那一条路**，一行保存逻辑都不重写） |
+
+🔴 **写盘不在后端**：开发目录是用户自己机器上的一个文件夹（浏览器用 File System Access API 选的），
+   后端只算"该铺什么"、只认"浏览器扫到了什么" —— 它一个字节都不碰对方的盘。
+   所以那两条读口是**两种入口、同一套判据**：配对、比对、能不能存全部只有 `_judge()` 这一处。
+🔴 **落盘布局是契约**（用户按它找文件）：`workspace/<可读名>-<块 uuid>/`，三份生成物在顶层。
+🔴 **合并进库的判据只有一处**：`write_dir` 调 `service.save()` —— 校验、体检、编译缓存失效全在那一处。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Iterable
+
+from . import devkit, validate
+from .sdk import (
+    BLOCK_BACKEND_FILE,
+    BLOCK_ENTRY,
+    BLOCK_MANIFEST,
+    LIB_SDK,
+    MAX_BODY_BYTES,
+)
+
+#: 铺出来的开发目录顶层那一层（名字是契约：用户按它找）。
+DEV_BLOCKS_DIR = 'workspace'
+
+#: 平台铺下来的生成物：**读回时一律静默跳过**（它们不是块包的一部分，进库只会把库弄脏）。
+#: 🔴 名字的真源在 `devkit`（那几份东西就是它写的）：块文件夹里两份 + 每个块一份主题，
+#:    开发目录顶层四份生成物 + 两份前端写的（Page 枚举 / 主题与控件清单）。
+PLATFORM_FILES: tuple[str, ...] = (
+    'api.open.d.ts',
+    'VERSION.lock',
+    devkit.README,
+    devkit.GUIDE,
+    devkit.BACKEND_LOCK,
+    devkit.PAGES_LOCK,
+    devkit.THEME,
+    devkit.CONTROLS,
+    devkit.REQUIREMENTS,
+)
+
+#: 从目录里读块时，哪些文件算"能读的文本"（其余一律跳过，不报成"不是文本文件"）。
+#: 🔴 浏览器那一侧**照这份名单扫**（导出报文里的 `rules.textExt`）—— 它不自己抄一份。
+TEXT_EXT: tuple[str, ...] = (
+    '.html',
+    '.htm',
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.ts',
+    '.css',
+    '.json',
+    '.yaml',
+    '.yml',
+    '.md',
+    '.txt',
+    '.py',
+    '.svg',
+)
+
+#: 扫描与读文件的几道上限（都是"防一次手滑把整台机器读完"，不是安全边界）。
+MAX_DEPTH = 3
+MAX_FILE_BYTES = 512 * 1024
+MAX_BUNDLE_CHARS = 8 * 1024 * 1024
+
+#: 爬目录时跳过的目录名（依赖 / 构建产物 / 缓存）。
+SKIP_DIRS: frozenset[str] = frozenset(
+    {'.git', '.venv', 'venv', '__pycache__', 'node_modules', 'dist', 'build', '.idea', '.vscode'}
+)
+
+#: 模块名那一段的形状（与清单里 `module` 的规矩同一份）。
+MODULE_SEGMENT_RE = re.compile(validate.MODULE_PATTERN.pattern)
+#: uuid 那一段的形状（文件夹名里带 uuid 时用它认出来）。
+UUID_SEGMENT_RE = re.compile(r'^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$')
+#: 文件夹名**末尾**那一段 uuid（导出铺的是 `<可读名>-<块 uuid>`；末尾这个词是判据，别放宽）。
+TRAILING_ID_RE = re.compile(r'([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$')
+
+#: 配对打分：清单命中压过一切，其余按"名字 + uuid / 名字 + 模块 / uuid"递减。
+MANIFEST_MATCH_SCORE = 200
+
+# ──────────────────────────── 认块时的打分（越大越可信） ────────────────────────────
+#
+# 🔴 四档名字分**必须**拉开：`_assign()` 要的是"全局择优"，而"名字和 uuid 都对上"
+#    与"只有一个同名"之间如果同分，选谁都行 —— 那就会出现"改一个块的文件夹，结果写掉另一个块"。
+#: 文件夹名 = `<可读名>-<块 uuid>`（导出铺的就是这个形状）⇒ **名字与身份同时对上**。
+SCORE_NAME_AND_ID = 160
+#: 文件夹名 = 块的可读名，**且**路径里那一段模块名也对得上（老布局 `<模块>/<可读名>` 的最硬线索）。
+SCORE_NAME_AND_MODULE = 120
+#: 文件夹名 = 块的可读名，库里只有一个块叫这个名字。
+SCORE_NAME = 80
+#: 文件夹名 = 块的可读名，但库里有好几个同名的 ⇒ 可疑，别当成唯一命中。
+SCORE_NAME_AMBIGUOUS = 40
+#: 文件夹名 = 块记录的 uuid（有人直接把 uuid 当文件夹名时的退路）。
+SCORE_ID = 30
+
+#: 扫描一个**顶层**目录时直接忽略的文件名（都是"开发目录说明 / 生成物"这一类）。
+#: ⚠️ 只对最外那一层生效：块文件夹**里面**的文件一个都不能跳过。
+_SKIP_ROOT_FILES: frozenset[str] = frozenset(
+    {
+        devkit.README.lower(),
+        devkit.GUIDE.lower(),
+        devkit.BACKEND_LOCK.lower(),
+        devkit.PAGES_LOCK.lower(),
+        devkit.THEME.lower(),
+        devkit.CONTROLS.lower(),
+        devkit.REQUIREMENTS.lower(),
+        'readme.md',
+        'readme.lock',
+        '.ds_store',
+        'thumbs.db',
+    }
+)
+
+
+def _model() -> Any:
+    """块表（用 `apps.get_model` 取：这个包在 app 还没注册完时也可能被 import）。
+
+    🔴 与 `service.MagicBlockService._model()` **逐字同一份**：这一层原来漏了它，于是
+       `read_dir` 一进门就 `NameError`（HTTP 上是 500，报文只肯说"服务端出错"）——
+       而这几条口（export / read / import）正是控制台那一趟来回的全部。取法要跟着 service 走：
+       直接 `from .models import MagicBlock` 会在 app 未就绪时炸。
+    """
+    from django.apps import apps
+
+    return apps.get_model('labull_framework', 'MagicBlock')
+
+
+def _reason(error: BaseException) -> str:
+    """一句能给人看的失败原因（`OSError` 常带 errno，那就连 errno 一起说）。"""
+    if isinstance(error, OSError) and error.errno is not None:
+        return f'{error.strerror or error.__class__.__name__}（errno {error.errno}）'
+    return str(error) or error.__class__.__name__
+
+
+def _failure(kind: str, where: str, message: str) -> dict:
+    """一条"这里没成"的记录。
+
+    🔴 `kind` 是给界面分组用的字面量（`dir` / `file` / `match`），**与 `message` 一起原样回给前端** ——
+       "哪里错了"和"为什么错"要分得开，用户才能一眼看出"是我路径给错了"还是"文件本身不合法"。
+       ⚠️ 浏览器扫出来的失败也走这一个形状（它报"读不了 / 不是文本 / 太大"，后端报"没配上块"）。
+    """
+    return {'kind': kind, 'where': _posix(where), 'message': message}
+
+
+def _safe_name(raw: str, fallback: str) -> str:
+    """把一段用户文本变成**能当文件夹名**的形式。
+
+    🔴 **保留中文**（块的文件夹名就是 `<可读名>-<uuid>`，可读名常常是中文），只清掉文件系统不接受的东西：
+       Windows 的 `<>:"/\\|?*`、控制字符、结尾的点与空格（`foo.` 在 Windows 上建不出来）、
+       以及全空白 / `.` / `..`。清完什么都不剩就退回 `fallback`。
+    """
+    text = re.sub(r'[<>:"/\\|?*\x00-\x1f]', '-', str(raw or ''))
+    text = re.sub(r'\s+', ' ', text).strip().rstrip('.')
+    return text[:80] or fallback
+
+
+def _same(left: Any, right: Any) -> bool:
+    """两个标识算不算同一个（**大小写敏感**、去首尾空白）。
+
+    🔴 **故意的**：Windows 上路径不区分大小写，但这里的用途是"文件夹名 ↔ 库里那条记录"的配对 ——
+       把 `Orders` 与 `orders` 当成同一个块，会让"改名/改模块"这类**需要人看见**的差异被悄悄吞掉。
+    """
+    return str(left or '').strip() == str(right or '').strip()
+
+
+def _posix(path: str) -> str:
+    """回给前端的路径一律用 `/`：它可能被粘进编辑器、也可能写进文档，`\\\\` 只会碍事。"""
+    return str(path or '').replace('\\', '/')
+
+
+def _strip_bom(text: str) -> str:
+    """去掉 UTF-8 BOM。
+
+    🔴 必须去：Windows 上记事本 / 某些导出工具会加 BOM。带着它的正文与库里的那一份
+       **永远不相等** ⇒ 每个块都被判成"改动过"，"读回改动"这个功能就废了。
+       ⚠️ 浏览器读文件也要去（`File.text()` 会把 BOM 解成第一个字符），见 `localfs.ts`。
+    """
+    return text[1:] if text.startswith('\ufeff') else text
+
+
+def _is_text(name: str) -> bool:
+    """这个文件名算不算"能读的文本"（认 `TEXT_EXT` 里的扩展名，大小写不敏感）。"""
+    return Path(name).suffix.lower() in TEXT_EXT
+
+
+def _is_platform_file(name: str) -> bool:
+    """平台随开发目录铺下来的生成物（`api.open.d.ts` / `*.lock*`）：读回时**静默跳过**、不进库。"""
+    return name in PLATFORM_FILES
+
+# ──────────────────────────── 出：库 → 开发包（后端只算，写盘在浏览器） ────────────────────────────
+
+
+def _block_folder(row: Any) -> str:
+    """一个块的文件夹名：`<可读名>-<块 uuid>`。
+
+    🔴 uuid 写在名字里是**故意的**：配对时"名字 + 身份"同时对上，就不必再靠"名字像不像"猜 ——
+       重名、改名、被挪进别的目录都照样认得出来（见 `_score` 里那条最硬的线索）。
+    """
+    short = str(getattr(row, 'id', '') or '')[:8] or 'block'
+    name = _safe_name(getattr(row, 'name', '') or short, short)
+    return f'{name}-{row.id}'
+
+
+def package_files(rows: Iterable[Any], tables: list[dict[str, Any]] | None = None) -> dict[str, str]:
+    """把"库里的行 + 模型形状"算成**一整个开发包**（相对路径 → 正文，一律 `/` 分隔）。
+
+    🔴 **纯函数**：不碰数据库、不写盘 —— 浏览器拿到它之后按路径写进用户选的目录。
+    🔴 一个块一个文件夹 = 一整个文件包，另加两份**平台生成物**：`api.open.d.ts`
+       （照这个块自己的后端生成，给编辑器补全用）与 `VERSION.lock`（导出时用的 SDK）；两者都不进库。
+    🔴 顶层那几份生成物（开发说明 / 精简版说明 / 后端清单）由 `devkit` 写正文，名字也归它
+       （见 `devkit` 顶上那一段）；`pages.lock.ts` **不在返回值里** —— 它是前端自己写的那一份
+       （路由表只有前端有）。
+    """
+    from .service import api_dts
+
+    files: dict[str, str] = {}
+    blocks = 0
+    for row in rows:
+        folder = _block_folder(row)
+        package = dict(getattr(row, 'files', None) or {})
+        if BLOCK_MANIFEST not in package:
+            # 🔴 没有清单就补一份：id 用**这个块自己的 uuid**，绝不编一个看起来合法的 ——
+            #    那会让下次"读回改动"报一条用户无法理解的错。
+            package[BLOCK_MANIFEST] = _starter_manifest(row)
+        for name, body in package.items():
+            files[f'{DEV_BLOCKS_DIR}/{folder}/{name}'] = str(body)
+        dts = api_dts(validate.routes_of(package.get(BLOCK_BACKEND_FILE) or ''))
+        if dts:
+            files[f'{DEV_BLOCKS_DIR}/{folder}/api.open.d.ts'] = dts
+        files[f'{DEV_BLOCKS_DIR}/{folder}/VERSION.lock'] = f'{LIB_SDK}\n'
+        blocks += 1
+    files[devkit.BACKEND_LOCK] = devkit.backend_lock_pyi(tables)
+    files[devkit.GUIDE] = devkit.dev_guide()
+    files[devkit.REQUIREMENTS] = requirements_text()
+    files[devkit.README] = devkit.dev_readme(blocks)
+    return files
+
+
+def requirements_text() -> str:
+    """这个项目的后端依赖清单（`BASE_DIR/requirements.txt` 的**逐字副本** + 一行说明）。
+
+    🔴 为什么要铺它：块后端跑在**项目的解释器**里，作者要 `import` 什么就得先装什么 ——
+       而块包里没有依赖文件、`backend.lock.pyi` 也只列"能 import 的库名"。给他一份可照抄的清单，
+       他就不必回来问"你们后端到底装了什么"。
+    ⚠️ 逐字抄（前面只加一行 `#` 注释）：它得能直接 `pip install -r` 用。
+    ⚠️ 项目里没有这个文件 / 读不出来就**如实写一行**，不编一份假的（那比没有更坏）。
+    """
+    from django.conf import settings
+
+    base = getattr(settings, 'BASE_DIR', None)
+    source = (Path(base) / 'requirements.txt') if base else None
+    if source is not None and source.is_file():
+        try:
+            body = source.read_text(encoding='utf-8')
+        except OSError as exc:
+            return f'# 读不到 {source}：{_reason(exc)}\n'
+        return (
+            f'# 这个项目的后端依赖清单（{source.name} 的逐字副本，导出时抄的）。\n'
+            '# 块后端与项目共用同一个解释器：要 import 什么，先确认它在这里面。\n'
+            f'{body}'
+        )
+    return (
+        '# 这个项目里没有 requirements.txt（或者 settings 里没有 BASE_DIR）——\n'
+        '# 块后端能 import 什么，以**这个项目实际装了的包**为准。\n'
+        '# 想知道装了哪些：在项目里跑一句 pip freeze。\n'
+    )
+
+
+def scan_rules() -> dict:
+    """浏览器"读回改动"时要照的规则（**判据只有这一处**，浏览器一条都不抄）。
+
+    🔴 浏览器只会干"读文件 / 写文件"：哪些扩展名算文本、哪些目录跳过、几层到顶、多大算太大，
+       全部照这一份走（它从导出报文里拿，见 `POST /magic-blocks/export` 的 `rules`）。
+       抄一份进 JS 的下场是"两边迟早漂"，而漂了的表现是"导出认得、读回认不得"。
+    """
+    return {
+        'entry': BLOCK_ENTRY,
+        'blocksDir': DEV_BLOCKS_DIR,
+        'textExt': list(TEXT_EXT),
+        'skipDirs': sorted(SKIP_DIRS),
+        'platformFiles': list(PLATFORM_FILES),
+        'rootSkipFiles': sorted(_SKIP_ROOT_FILES),
+        'maxDepth': MAX_DEPTH,
+        'maxFileBytes': MAX_FILE_BYTES,
+        'maxBodyBytes': MAX_BODY_BYTES,
+    }
+
+
+def export_package() -> dict:
+    """`POST /magic-blocks/export` 的全部答案：一整个开发包 + 读回时要照的规则。
+
+    🔴 它**不写盘**（写盘在浏览器那一侧，目录是用户自己机器上的）：
+       回话里的 `files` 就是"该铺什么"，键是相对路径。
+    """
+    from ..canvas.data import shape
+
+    rows = list(_model().objects.all().order_by('name'))
+    tables = (shape() or {}).get('tables') or []
+    return {'files': package_files(rows, tables), 'blocks': len(rows), 'rules': scan_rules()}
+
+
+def _starter_manifest(row: Any) -> str:
+    """包里没有清单时补的那一份（四个键全必填）。"""
+    name = row.name or str(row.id)[:8]
+    return (
+        '# 块包必备文件之一：这个块的身份与元信息。四个键全部必填，只有这四个。\n'
+        f'id: "{row.id}"\n'
+        f'module: "{row.module or "home"}"\n'
+        f'name: "{name}"\n'
+        f'brief: "{row.brief or name}"\n'
+    )
+
+
+# ──────────────────────────── 回：目录 → 逐块对比（两种入口，一套判据） ────────────────────────────
+
+
+class _Collect:
+    """一次扫描攒下来的东西。
+
+    ⚠️ 服务器读盘（`read_dir`）与浏览器递上来（`scan_folders`）都用它：前者的失败来自
+       `try/except OSError`，后者的失败由浏览器报（它读不了 / 不是文本 / 太大）。
+    """
+
+    def __init__(self) -> None:
+        self.folders: list[dict] = []
+        self.files = 0
+        self.failures: list[dict] = []
+        #: 因为深度上限而没往下走 ⇒ 不能说"目录里没有就是删了"。
+        self.truncated = False
+
+
+def scan_folders(upload: dict, include_missing: bool = False) -> dict:
+    """**浏览器扫到的**那个目录，与库里的块逐块比一遍（只读，不写库）。
+
+    :param upload: `{'root'?, 'folders': [{'where', 'files'}], 'failures'?, 'truncated'?}`
+        —— 形状由 `frontend/magic-block/src/localfs.ts` 的扫描器给出（它照 `scan_rules()` 走）。
+    :param include_missing: 默认 `False` —— "没扫到"不等于"要删掉"，默认列出来只会误导。
+
+    🔴 这里**看不到对方的盘**（也不需要）：递上来的就是事实。配对 / 比对 / 能不能存仍然只有
+       `_judge()` 这一处判据 —— 换一个入口不换规矩。
+    """
+    given = upload if isinstance(upload, dict) else {}
+    collect = _Collect()
+    collect.truncated = given.get('truncated') is True
+    for item in given.get('failures') or []:
+        if not isinstance(item, dict):
+            continue
+        collect.failures.append(
+            _failure(str(item.get('kind') or 'file'), str(item.get('where') or ''), str(item.get('message') or ''))
+        )
+    for item in given.get('folders') or []:
+        if not isinstance(item, dict):
+            continue
+        where = _posix(str(item.get('where') or ''))
+        raw = item.get('files')
+        files = {str(name): str(body) for name, body in raw.items()} if isinstance(raw, dict) else {}
+        collect.files += len(files)
+        collect.folders.append(
+            {'abs': where, 'where': where, 'segments': [seg for seg in where.split('/') if seg], 'files': files}
+        )
+    return _judge(str(given.get('root') or ''), collect, include_missing)
+
+
+def read_dir(path: str, include_missing: bool = False) -> dict:
+    """读一个**服务器上的**目录，与库里的块**逐块比一遍**（只读，不写库）。
+
+    ⚠️ 控制台那条路走 `scan_folders()`（开发目录在用户自己机器上）；这一条留给
+       "源码本来就在服务器上"的用法（CLI / 脚本）。两条入口的判断完全一样。
+    :param include_missing: 默认 `False` —— 路径往往只指到一个块或一个模块的文件夹，
+        "没扫到"不等于"要删掉"，默认列出来只会误导。
+    """
+    given = str(path or '').strip()
+    collect = _Collect()
+    if not given:
+        collect.failures.append(_failure('dir', '', '还没有给目录路径'))
+        return _result('', collect, [], [])
+    if not os.path.isabs(given):
+        collect.failures.append(_failure('dir', given, '要一个**绝对路径**（相对路径在服务端没有意义）'))
+        return _result(given, collect, [], [])
+    root = Path(given).resolve()
+    if not root.is_dir():
+        collect.failures.append(
+            _failure('dir', str(root), '这个目录不存在或读不了（后端跑在容器里时，那个目录要先挂进去）')
+        )
+        return _result(str(root), collect, [], [])
+
+    _discover(root, collect, [], 0)
+    return _judge(_posix(str(root)), collect, include_missing)
+
+
+def _judge(root: str, collect: _Collect, include_missing: bool) -> dict:
+    """配对 + 逐文件比 + 提前算"能不能存"（**两种读入口共用这一处**）。"""
+    pool = list(_model().objects.all())
+    matched = _assign(collect.folders, pool)
+    used = {pool[index].id: collect.folders[disk]['where'] for disk, index in matched.items()}
+    blocks: list[dict] = []
+    unmatched: list[str] = []
+    for index, disk in enumerate(collect.folders):
+        hit = matched.get(index)
+        if hit is None:
+            unmatched.append(disk['where'] or '（选中的目录本身）')
+            collect.failures.append(_failure('match', disk['abs'], _explain(disk, pool, used)))
+            continue
+        blocks.append(_diff(pool[hit], disk))
+
+    if include_missing:
+        for row in pool:
+            if row.id in used:
+                continue
+            blocks.append(
+                {
+                    'id': row.id,
+                    'name': row.name,
+                    'folder': '',
+                    'where': '',
+                    'status': 'missing',
+                    'changedFiles': sorted(row.files or {}),
+                    'files': {},
+                    'canApply': False,
+                    'blockedWhy': '这个块在目录里找不到（要保存它，请把它的文件夹放进目录）',
+                }
+            )
+
+    # 🔴 每条 diff 上用**保存那套判据**提前算结论（"扫描说能存、真存又不过"是同一件事的两个说法）。
+    for item in blocks:
+        if item.get('canApply', False) and item['files']:
+            messages = [message for _stage, message in validate.check_block(item['files'])]
+            if messages:
+                item['canApply'] = False
+                item['blockedWhy'] = '校验没过：' + '；'.join(messages)
+
+    order = {'modified': 0, 'unchanged': 1, 'missing': 2}
+    blocks.sort(key=lambda item: (order.get(item['status'], 9), item['folder']))
+    return _result(root, collect, blocks, unmatched)
+
+
+def _result(root: str, collect: _Collect, blocks: list[dict], unmatched: list[str]) -> dict:
+    """扫描结果（形状与前端那份一致）。"""
+    return {
+        'root': _posix(root),
+        'folders': len(collect.folders),
+        'files': collect.files,
+        'blocks': blocks,
+        'unmatched': unmatched,
+        'failures': collect.failures,
+        # "目录里没有它"这条判据只有在**整棵树都走完了**的情况下才可信。
+        'complete': not collect.truncated,
+    }
+
+
+def _discover(root: Path, collect: _Collect, segments: list[str], depth: int) -> None:
+    """走一遍目录，找出所有候选块文件夹。
+
+    🔴 候选判据：这一层有入口 `index.open.html`，或者"到底了"（没有子文件夹）——
+       坏包与空文件夹也要交给配对那一步去认，不能静默跳过。
+    """
+    try:
+        entries = sorted(root.iterdir(), key=lambda item: item.name)
+    except OSError as exc:
+        collect.failures.append(_failure('dir', str(root), f'读不了这个文件夹：{_reason(exc)}'))
+        return
+    dirs = [item for item in entries if item.is_dir() and not item.is_symlink()]
+    files = [item for item in entries if item.is_file()]
+
+    if not dirs or any(item.name == BLOCK_ENTRY for item in files):
+        collect.folders.append(_disk(root, segments, collect))
+        return
+
+    for item in files:
+        if not segments and item.name.lower() in _SKIP_ROOT_FILES:
+            continue
+        collect.failures.append(
+            _failure(
+                'file',
+                str(item),
+                f'这一层直接放着一份文件，但它自己不是块文件夹、也没有 {BLOCK_ENTRY}，文件没有归属',
+            )
+        )
+    for item in dirs:
+        if item.name in SKIP_DIRS:
+            continue
+        if depth >= MAX_DEPTH:
+            collect.truncated = True
+            collect.failures.append(
+                _failure('dir', str(item), f'超过最大层数 {MAX_DEPTH} 层还没见到 {BLOCK_ENTRY}，没有继续往下找')
+            )
+            continue
+        _discover(item, collect, [*segments, item.name], depth + 1)
+
+
+def _disk(directory: Path, segments: list[str], collect: _Collect) -> dict:
+    """磁盘上的一个候选块文件夹（读它的文本文件，包内子目录逐层加前缀）。"""
+    return {
+        'abs': str(directory),
+        'where': '/'.join(segments),
+        'segments': list(segments),
+        'files': _read_files(directory, collect),
+    }
+
+
+def _read_files(directory: Path, collect: _Collect) -> dict[str, str]:
+    """读一个文件夹里的文本文件；子目录照原样拼成相对路径（`js/app.js`）。"""
+    files: dict[str, str] = {}
+    try:
+        entries = sorted(directory.iterdir(), key=lambda item: item.name)
+    except OSError as exc:
+        collect.failures.append(_failure('dir', str(directory), f'读不了这个文件夹：{_reason(exc)}'))
+        return files
+    for entry in entries:
+        if entry.is_symlink():
+            # 🔴 不跟软链接：可能绕成环（扫描永不结束），也可能指到项目外面。
+            collect.failures.append(
+                _failure('file', str(entry), '这是一个软链接，已跳过（不跟软链接，避免绕环 / 读到项目外面）')
+            )
+            continue
+        if entry.is_dir():
+            if entry.name in SKIP_DIRS:
+                continue
+            for name, body in _read_files(entry, collect).items():
+                files[f'{entry.name}/{name}'] = body
+            continue
+        if not entry.is_file() or _is_platform_file(entry.name):
+            # 平台随开发目录铺下来的那几份**静默跳过**：报出来只会给每个块平白添几条失败。
+            continue
+        if not _is_text(entry.name):
+            collect.failures.append(
+                _failure('file', str(entry), f'不是文本文件（认得的扩展名：{" ".join(TEXT_EXT)}），已跳过')
+            )
+            continue
+        try:
+            size = entry.stat().st_size
+        except OSError as exc:
+            collect.failures.append(_failure('file', str(entry), f'读不到文件大小：{_reason(exc)}'))
+            continue
+        if size > MAX_FILE_BYTES:
+            collect.failures.append(
+                _failure(
+                    'file',
+                    str(entry),
+                    f'文件 {round(size / 1024)} KB 超过上限 {MAX_FILE_BYTES // 1024} KB，已跳过',
+                )
+            )
+            continue
+        try:
+            files[entry.name] = _strip_bom(entry.read_text(encoding='utf-8'))
+            collect.files += 1
+        except (OSError, UnicodeDecodeError) as exc:
+            collect.failures.append(_failure('file', str(entry), f'读不了这个文件：{_reason(exc)}'))
+    return files
+
+
+def _diff(row: Any, disk: dict) -> dict:
+    """库里那一包与目录里那一包逐文件比。"""
+    db_files = dict(row.files or {})
+    disk_files = disk['files']
+    changed = sorted(name for name, body in disk_files.items() if db_files.get(name) != body)
+    removed = sorted(name for name in db_files if name not in disk_files)
+    size = sum(len(body) for body in disk_files.values())
+    blocked = f'这一包超过上限 {MAX_BUNDLE_CHARS // 1024} KB，没有读全' if size > MAX_BUNDLE_CHARS else ''
+    return {
+        'id': row.id,
+        'name': row.name,
+        'module': row.module or _module_segment(disk['segments']),
+        'brief': row.brief,
+        'folder': _posix(disk['abs']),
+        'where': disk['where'],
+        'status': 'unchanged' if not changed and not removed else 'modified',
+        'changedFiles': changed,
+        'files': disk_files,
+        'canApply': not blocked,
+        'blockedWhy': blocked,
+    }
+
+
+# ──────────────────────────── 配对（全局择优） ────────────────────────────
+
+
+def _manifest_of(disk: dict) -> dict:
+    """这个文件夹的清单：认块时它说的 `id` 是最高置信依据。
+
+    🔴 `present` 与 `id` **分开看**：有清单就只认清单（哪怕清单本身写坏了），
+       只有没清单才退回名字 / uuid 打分 —— 名字像不等于同一个块。
+    """
+    files = disk['files']
+    if BLOCK_MANIFEST not in files:
+        return {'present': False, 'id': '', 'issues': []}
+    manifest, issues = validate.read_manifest(files)
+    return {'present': True, 'id': (manifest or {}).get('id', ''), 'issues': issues}
+
+
+def _folder_id(folder: str) -> str:
+    """文件夹名**末尾**那段 uuid（导出铺的是 `<可读名>-<uuid>`；没有就是空串）。"""
+    match = TRAILING_ID_RE.search(folder)
+    return match.group(1) if match else ''
+
+
+def _folder_name(folder: str) -> str:
+    """文件夹名去掉末尾那段 uuid 之后剩下的那部分（就是块的可读名）。"""
+    match = TRAILING_ID_RE.search(folder)
+    return folder[: match.start()].rstrip('-').strip() if match else folder
+
+
+def _module_segment(segments: list[str]) -> str:
+    """路径里那一段能不能当模块名（`<模块>/<可读名>/` 的倒数第二段）。
+
+    🔴 `workspace` 要排掉：它是开发目录自己那一层（`workspace/<可读名>-<uuid>/`），
+       把它当成模块名会让"老布局那一档打分"凭空高一级（而它一个字都不说明）。
+    """
+    if len(segments) < 2:
+        return ''
+    candidate = segments[-2]
+    if candidate == DEV_BLOCKS_DIR:
+        return ''
+    return candidate if validate.MODULE_PATTERN.match(candidate) else ''
+
+
+def _score(disk: dict, row: Any, pool: list[Any]) -> int:
+    """一个文件夹与一个块有多对得上（0 = 对不上）。"""
+    folder = disk['segments'][-1] if disk['segments'] else ''
+    if not folder:
+        return 0
+    tail = _folder_id(folder)
+    if tail and _same(row.id, tail):
+        # 🔴 导出铺的就是这个形状：名字与身份**同时**对上，比"名字 + 模块"还硬。
+        return SCORE_NAME_AND_ID if _same(row.name, _folder_name(folder)) else SCORE_ID
+    module_segment = _module_segment(disk['segments'])
+    if _same(row.name, folder):
+        if module_segment and _same(row.module, module_segment):
+            return SCORE_NAME_AND_MODULE
+        same_name = len([other for other in pool if _same(other.name, folder)])
+        return SCORE_NAME_AMBIGUOUS if same_name > 1 else SCORE_NAME
+    return SCORE_ID if _same(row.id, folder) else 0
+
+
+def _assign(disks: list[dict], pool: list[Any]) -> dict[int, int]:
+    """每个块文件夹配库里的哪一条（返回 `{文件夹下标: 池下标}`）。
+
+    🔴 **清单优先**，而且带清单的文件夹**不进**打分段：清单里的 id 不在库里 = 这个块还没建过，
+       随便配一个库里的块，下一步就会拿这一包把那条记录覆盖掉。
+    🔴 要用分数**全局择优**而不是贪心：贪心看扫描顺序，会出现"uuid 文件夹把别人的块抢走"。
+    """
+    manifests = [_manifest_of(disk) for disk in disks]
+    candidates: list[tuple[int, int, int]] = []
+    for disk_index, manifest in enumerate(manifests):
+        if manifest['present']:
+            if not manifest['id']:
+                continue
+            for pool_index, row in enumerate(pool):
+                if _same(row.id, manifest['id']):
+                    candidates.append((MANIFEST_MATCH_SCORE, disk_index, pool_index))
+                    break
+            continue
+        for pool_index, row in enumerate(pool):
+            score = _score(disks[disk_index], row, pool)
+            if score > 0:
+                candidates.append((score, disk_index, pool_index))
+
+    # 分数降序；同分按（文件夹先、块先）—— 稳定定序，结果与扫描顺序无关、可复现。
+    candidates.sort(key=lambda item: (-item[0], item[1], item[2]))
+    taken_disk: set[int] = set()
+    taken_pool: set[int] = set()
+    out: dict[int, int] = {}
+    for _score_value, disk_index, pool_index in candidates:
+        if disk_index in taken_disk or pool_index in taken_pool:
+            continue
+        taken_disk.add(disk_index)
+        taken_pool.add(pool_index)
+        out[disk_index] = pool_index
+
+    # 兜底：只选了一个块的文件夹（路径里没有块名那一段），且它包里**没有清单**。
+    if len(disks) == 1 and not out and pool and not disks[0]['segments'] and not manifests[0]['present']:
+        out[0] = 0
+    return out
+
+
+def _explain(disk: dict, pool: list[Any], used: dict[str, str]) -> str:
+    """认不出时到底该说什么（原因要能直接照做，不能只说"没匹配上"）。"""
+    manifest = _manifest_of(disk)
+    where = disk['where'] or '（选中的目录本身）'
+    if manifest['present']:
+        if manifest['issues']:
+            return (
+                f'「{where}」包里有清单，但清单里的块 id 读不出来：{"；".join(manifest["issues"])}。'
+                f'认块只认清单里的 id —— 请先把 {BLOCK_MANIFEST} 改对'
+            )
+        if manifest['id'] in used:
+            return f'「{where}」清单里的 uuid={manifest["id"]} 已经被目录里的「{used[manifest["id"]]}」占了'
+        return (
+            f'「{where}」清单里的 uuid={manifest["id"]} 在库里没有对应的块：这个块可能还没建过，'
+            '也可能清单里的 id 被改过'
+        )
+    folder = disk['segments'][-1] if disk['segments'] else ''
+    tail = _folder_id(folder)
+    if not folder:
+        sample = '、'.join(f'{row.module or "(无模块)"}/{row.name}' for row in pool[:5])
+        return (
+            f'「{where}」这一层本身就是一份 {BLOCK_ENTRY}，但文件夹名与路径里没有任何一段对得上库里的块'
+            f'（库里有 {len(pool)} 个块：{sample}…）—— 认不出是哪一块'
+        )
+    id_match = next((row for row in pool if _same(row.id, folder)), None)
+    if id_match is not None and id_match.id in used:
+        return f'「{where}」对应的块 uuid={id_match.id} 已经被目录里的「{used[id_match.id]}」占了，同一个块只认一处'
+    if tail:
+        hit = next((row for row in pool if _same(row.id, tail)), None)
+        if hit is not None and hit.id in used:
+            return f'「{where}」文件夹名末尾的 uuid={tail} 已经被目录里的「{used[tail]}」占了，同一个块只认一处'
+        if hit is None:
+            return (
+                f'「{where}」文件夹名末尾是一个 uuid（{tail}），但库里没有 id 为它的块'
+                f'（导出时那种名字是 `<可读名>-<uuid>`；这个块可能已经删了，或者 uuid 被改过）'
+            )
+    name_matches = [row for row in pool if _same(row.name, folder) or _same(row.name, _folder_name(folder))]
+    if name_matches and all(row.id in used for row in name_matches):
+        return f'「{where}」的名字「{folder}」对上了 {len(name_matches)} 个块，但它们都已经被别的文件夹占了'
+    if UUID_SEGMENT_RE.match(folder):
+        return f'「{where}」看起来是一个 uuid，但库里没有 id 为 {folder} 的块（这个块可能还没建过）'
+    return (
+        f'「{where}」找不到对应的块：库里既没有叫「{folder}」的可读名，也没有这个 uuid —— '
+        '文件夹名要么是导出时那种 `<可读名>-<uuid>`，要么直接用它那条记录的 uuid'
+    )
+
+
+# ──────────────────────────── 从目录写回库 ────────────────────────────
+
+
+def write_dir(items: list[dict], actor: str = '') -> dict:
+    """把（`scan_folders` / `read_dir` 读回来的）这些块写回库。
+
+    🔴 走的是**保存那一条路**（`service.save`）：同样的校验、同样的体检、同样的"写库之后才换注册表"。
+       这里**一行保存逻辑都不重写** —— 重写一份的后果是"扫描说能存、真存又不过"。
+    🔴 一个块失败只报它自己（`results` 逐条带原因），不拖累别的块。
+    """
+    from .service import BlockNotFound, MagicBlockService, SaveRejected
+
+    service = MagicBlockService()
+    out: dict = {'saved': 0, 'failed': 0, 'results': []}
+    for item in items or []:
+        block_id = str(item.get('id') or '')
+        entry = {'id': block_id, 'name': str(item.get('name') or ''), 'ok': False, 'error': '', 'issues': []}
+        try:
+            saved = service.save(
+                block_id=block_id,
+                module=str(item.get('module') or ''),
+                name=str(item.get('name') or ''),
+                brief=str(item.get('brief') or ''),
+                files=item.get('files') or {},
+                actor=actor,
+            )
+        except (SaveRejected, BlockNotFound) as exc:
+            issues = list(getattr(exc, 'issues', []) or [])
+            entry['issues'] = issues
+            entry['error'] = '；'.join(issues) or exc.message
+        except Exception as exc:  # noqa: BLE001 —— 一个块失败不拖累其它块
+            entry['error'] = f'{type(exc).__name__}: {_reason(exc)}'
+        else:
+            entry.update({'ok': True, 'id': saved.id, 'name': saved.name})
+            out['saved'] += 1
+            out['results'].append(entry)
+            continue
+        out['failed'] += 1
+        out['results'].append(entry)
+    return out