labull-framework 1.0.4__tar.gz → 1.1.1__tar.gz

{labull_framework-1.0.4/labull_framework.egg-info → labull_framework-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 1.0.4
+Version: 1.1.1
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-1.0.4 → labull_framework-1.1.1}/labull_framework/env.py

@@ -1,235 +1,238 @@
-"""环境变量的唯一入口：读值、加载 `.env`、给块的配置白名单，以及**有哪几个变量**这份清单。
-
-🔴 `.env` 解析器只有这一处（Django 自己不读 `.env`，标准库也没有这回事）。
-   两处各解析一遍的后果是"平台读得到、你的代码读不到" —— 最难查的一类不一致。
-🔴 `ENV_ITEMS` 是"平台读哪些环境变量"的**唯一真源**：开发包里的 `backend.lock.pyi`
-   照它铺一份给块作者看，登录那一组的必填清单与 `.env` 例子也从它取（见 `auth/sso.py`）。
-"""
-
-from __future__ import annotations
-
-import os
-import re
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Mapping
-
-from .magic_block.sdk import BLOCK_CONFIG_PREFIX, BLOCK_DEEPCHECK, BLOCK_PROBE, BLOCK_REQUIRES
-
-#: 给块的配置前缀：`BLOCK_OCR_KEY=abc` ⇒ 块后端里 `ctx.config['OCR_KEY'] == 'abc'`。
-#: 🔴 这是**白名单**（不是黑名单）：想让块读一项，就给那个变量加这个前缀，不用改库的代码。
-#: ⚠️ 字面量的真源在 `sdk`（上面那行 import）—— 这里**不许**再写一遍 `'BLOCK_'`。
-
-#: `.env` 里一行的形状。允许 `export` 前缀、行首缩进、`=` 两边空白；
-#: 🔴 **不剥行内注释**（值里真带 `#` 的密钥不该被截断）、**不做变量展开**（那会让"谁先谁后"变成隐式规则）。
-_ENV_LINE = re.compile(r'^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$')
-
-
-def load_env_file(path: str | Path) -> None:
-    """把一份 `.env` 并进 `os.environ`（在 `settings.py` 的**第一行**调一次）。
-
-    🔴 必须排在读 `os.environ` 之前：顺序反了，`.env` 里给的值读不到，
-       而报出来的症状是"我配了，它还是不生效"。
-    🔴 `.env` **覆盖**进程环境：它是项目的配置真源，而进程里可能留着同名的外部变量。
-    🔴 用 `utf-8-sig` 读：编辑器存"UTF-8 带 BOM"时那个 BOM 会粘在第一个键名前面，
-       而 `^\\s*` 不匹配它 ⇒ 第一行**静默消失**（症状是"我明明配了它"）。
-    ⚠️ 文件不在 = 什么都不做（不抛、不报）：缺配置该由**用到它的那一刻**报出来。
-    """
-    source = Path(path)
-    if not source.is_file():
-        return
-    values: dict[str, str] = {}
-    for line in source.read_text(encoding='utf-8-sig').splitlines():
-        match = _ENV_LINE.match(line)
-        if not match:
-            continue  # 空行与 `#` 注释都走这一条
-        raw = match.group(2).strip()
-        quoted = len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ('"', "'")
-        values[match.group(1)] = raw[1:-1] if quoted else raw
-    os.environ.update(values)
-
-
-def read_env(name: str) -> str:
-    """读一个环境变量（空串当没写 —— `.env` 里 `KEY=` 是常态），去掉首尾空白。"""
-    return str(os.environ.get(name, '') or '').strip()
-
-
-def block_config(env: Mapping[str, str] | None = None) -> dict[str, str]:
-    """给块的配置：带 `BLOCK_` 前缀的那几个，**剥掉前缀当键**。
-
-    🔴 没配的键在 `ctx.config` 上**不存在**（别拿 `None` 当默认值使，先判 `'X' in ctx.config`）；
-       配成空串的**照给**（`BLOCK_X=` ⇒ `ctx.config['X'] == ''`）。
-    🔴 剥完是空串的**不算键**（`BLOCK_=` 不可能是名字）。
-    🔴 别的变量一个都不给块 —— 数据库连接串、SSO 密钥都不在这里。
-    """
-    source = os.environ if env is None else env
-    result: dict[str, str] = {}
-    for name, value in source.items():
-        if not name.startswith(BLOCK_CONFIG_PREFIX):
-            continue
-        key = name[len(BLOCK_CONFIG_PREFIX):]
-        if key:
-            result[key] = value
-    return result
-
-
-# ──────────────────────────── "有哪几个环境变量"这份清单 ────────────────────────────
-
-#: 登录那一组的组名。🔴 `auth/sso.py` 按它取必填清单（**不抄第二份名单**）。
-LOGIN_GROUP = '登录（Authing OIDC）'
-
-
-@dataclass(frozen=True)
-class EnvItem:
-    """一个环境变量在**开发包**里被看到的样子。
-
-    🔴 `hint` 是"能直接粘进 `.env` 的一行"：缺必填时那句报错就照它说（见 `auth/sso.py`）——
-       只说"缺了"的报错，用户还得自己去翻文档才知道那一行该怎么写。
-    🔴 **这里永远不写值**：这份清单会铺进开发包（跟着块作者的编辑器走），而环境里有
-       数据库连接串与登录密钥。块的配置面是白名单，同一个道理。
-    """
-
-    #: 变量名。⚠️ 前缀那一条写的是 `BLOCK_*` —— 它不是一个真名字，是一族名字的前缀。
-    name: str
-    #: 这个变量管什么（一句人话）。
-    brief: str
-    #: 能直接粘进 `.env` 的一行（没有例子就是空串）。
-    hint: str = ''
-    #: 必填吗（缺了就跑不起来的那几项）。
-    required: bool = False
-    #: 分组（开发包里按它分段；"哪几项是登录用的"也从这里取）。
-    group: str = '平台'
-
-
-#: 平台读的**全部**环境变量 —— 唯一真源。
-#:
-#: 🔴 它是一份**清单**，不是"读值的入口"：各处仍然各读各的（`read_env('DATABASE_URL')` 之类）。
-#:    两者对不上的风险由 `tools/sdk-check-py.mjs` 兜住：它扫一遍库里所有 `read_env('<名字>')`
-#:    字面量，漏在这份清单外的当场报红。
-ENV_ITEMS: tuple[EnvItem, ...] = (
-    # ── 登录（Authing OIDC）：这四项不配就没人能登录 ──
-    EnvItem(
-        name='SSO_ISSUER',
-        brief='Authing 的 OIDC 发证地址（OIDC discovery 就在它下面）',
-        hint='SSO_ISSUER=https://<你的域名>.authing.cn/oidc',
-        required=True,
-        group=LOGIN_GROUP,
-    ),
-    EnvItem(
-        name='SSO_CLIENT_ID',
-        brief='Authing 应用的 App ID',
-        hint='SSO_CLIENT_ID=<Authing 应用的 App ID>',
-        required=True,
-        group=LOGIN_GROUP,
-    ),
-    EnvItem(
-        name='SSO_CLIENT_SECRET',
-        brief='Authing 应用的 App Secret（**只在服务端**用，别带进前端）',
-        hint='SSO_CLIENT_SECRET=<Authing 应用的 App Secret>',
-        required=True,
-        group=LOGIN_GROUP,
-    ),
-    EnvItem(
-        name='SSO_REDIRECT_URI',
-        brief='登录回调地址（必须与 Authing 应用里登记的那个逐字一致）',
-        hint='SSO_REDIRECT_URI=http://localhost:8000/auth/callback',
-        required=True,
-        group=LOGIN_GROUP,
-    ),
-    EnvItem(
-        name='SSO_WEB_ORIGIN',
-        brief='登录成功后把人送回哪个前端地址（不写就用 auth/sso.py 里的默认值）',
-        hint='SSO_WEB_ORIGIN=http://localhost:5173',
-        group=LOGIN_GROUP,
-    ),
-    # ── 跨源与数据库 ──
-    EnvItem(
-        name='CORS_ORIGIN',
-        brief='允许跨源访问的前端地址（逗号分隔）；它同时是 CSRF 信任名单的来源',
-        hint='CORS_ORIGIN=http://localhost:5173',
-        group='跨源与数据库',
-    ),
-    EnvItem(
-        name='DATABASE_URL',
-        brief='项目数据库连接串（postgres://… 形式）；不写就用项目自己 settings 里的 DATABASES',
-        hint='DATABASE_URL=postgres://user:password@127.0.0.1:5432/app',
-        group='跨源与数据库',
-    ),
-    # ── 平台开关 ──
-    EnvItem(
-        name='BOOTSTRAP_ADMIN_WORK_IDS',
-        brief='管理员名单：启动时把这些人设成 is_staff，名单之外的一律清掉（逗号分隔，上限 200；没配就是没有管理员）',
-        hint='BOOTSTRAP_ADMIN_WORK_IDS=1001',
-        group='平台开关',
-    ),
-    EnvItem(
-        name='LABULL_SCHEMA_CANVAS',
-        brief='数据模型那一页的开关：on 常开 / auto 只在 DEBUG 开 / 其余（默认）不开',
-        hint='LABULL_SCHEMA_CANVAS=on',
-        group='平台开关',
-    ),
-    EnvItem(
-        name='LABULL_CONTRACT_PATH',
-        brief='模型形状那份 JSON 的落点（**兜底**用：画布的基线默认是从提交里的源码算的；默认 .labull/contract.json）',
-        hint='LABULL_CONTRACT_PATH=.labull/contract.json',
-        group='平台开关',
-    ),
-    EnvItem(
-        name='LABULL_BASELINE_REV',
-        brief="画布拿哪一版当\"上一版\"：留空＝HEAD~1（上一次提交改了什么）/ head＝只看没提交的改动 / off＝不做差异 / 也可以给一个提交号或分支",
-        hint='LABULL_BASELINE_REV=HEAD~1',
-        group='平台开关',
-    ),
-    EnvItem(
-        name='LABULL_BASELINE_IGNORE_APPS',
-        brief='画布比对时**不参与**的 app（逗号/空格分隔，例如 labull_framework）—— 这些 app 的表照样画，只是不带"上一版 vs 现在"的差异色',
-        hint='LABULL_BASELINE_IGNORE_APPS=labull_framework',
-        group='平台开关',
-    ),
-    # 🔴 下面两条是**体检**那一侧的应急开关（名字的真源在 `magic_block/sdk.py`，不在这里手抄）：
-    #    默认都开 —— 关掉等于"字段改名这类问题回到运行期才现形"，只该在排查误报时临时用一下。
-    EnvItem(
-        name=BLOCK_DEEPCHECK,
-        brief='块的「引用深检」总开关：off 退回只判形状（字段 / 模型改了名就不再提前报出来）',
-        hint=f'{BLOCK_DEEPCHECK}=off',
-        group='平台开关',
-    ),
-    EnvItem(
-        name=BLOCK_PROBE,
-        brief='体检里「把 handler 真跑一遍」那一半的开关：off 只留静态判据（不执行任何块代码）',
-        hint=f'{BLOCK_PROBE}=off',
-        group='平台开关',
-    ),
-    # 🔴 依赖声明（`requires`）那一层的开关（名字的真源在 `magic_block/sdk.py`）：
-    #    默认 `error`（1.0.1 起）—— "先警告、后强制"里的**后强制**已经落地了。
-    #    ⚠️ 代价如实说：库里那些**还没声明**的存量块会集体判不合格（全部停用），
-    #       所以升级前先用 `manage.py labull_requires --write` 把扫得到的声明批量补进库
-    #       （那条命令就是为这个默认值而存在的：它是这条路上唯一的恢复口）。
-    EnvItem(
-        name=BLOCK_REQUIRES,
-        brief='块「依赖声明」（requires）那一层的开关：off 整段不跑 / warn 只提示不拦（要显式写）/ error（默认）变成硬判据',
-        hint=f'{BLOCK_REQUIRES}=warn',
-        group='平台开关',
-    ),
-    # 🔴 体检那条链一次开几个口子（名字的真源在 `magic_block/parallel.py` 的 `ENV_WORKERS`）。
-    #    ⚠️ 它是**性能旋钮、不是判据**：写错一个数（0 / 64 / 一句乱码）会被夹到 1..8，不该让体检报错。
-    #    它在这里的意义是"使用者的清单里能看见这个开关"（`backend.lock.pyi` 就是按 ENV_ITEMS 铺的）。
-    EnvItem(
-        name='LABULL_BLOCK_WORKERS',
-        brief='启动体检 / 全量校验一次开几个子进程（默认 4，夹在 1..8）：机器小就往下调，写 1 退回串行',
-        hint='LABULL_BLOCK_WORKERS=2',
-        group='平台开关',
-    ),
-    # ── 块的配置面 ──
-    EnvItem(
-        name=f'{BLOCK_CONFIG_PREFIX}*',
-        brief='块的配置面：**只有**带这个前缀的变量才进 ctx.config（前缀剥掉当键，别的变量一个都不给块）',
-        hint=f'{BLOCK_CONFIG_PREFIX}OCR_KEY=xxx',
-        group='块的配置',
-    ),
-)
-
-
-def required_items(group: str) -> tuple[EnvItem, ...]:
-    """某一组里必填的那几项（顺序 = `ENV_ITEMS` 里的顺序，所以报错顺序稳定）。"""
-    return tuple(item for item in ENV_ITEMS if item.group == group and item.required)
+"""环境变量的唯一入口：读值、加载 `.env`、给块的配置白名单，以及**有哪几个变量**这份清单。
+
+🔴 `.env` 解析器只有这一处（Django 自己不读 `.env`，标准库也没有这回事）。
+   两处各解析一遍的后果是"平台读得到、你的代码读不到" —— 最难查的一类不一致。
+🔴 `ENV_ITEMS` 是"平台读哪些环境变量"的**唯一真源**：开发包里的 `backend.lock.pyi`
+   照它铺一份给块作者看，登录那一组的必填清单与 `.env` 例子也从它取（见 `auth/sso.py`）。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+from .magic_block.sdk import BLOCK_CONFIG_PREFIX, BLOCK_DEEPCHECK, BLOCK_REQUIRES, BLOCK_TYPE
+
+#: 给块的配置前缀：`BLOCK_OCR_KEY=abc` ⇒ 块后端里 `ctx.config['OCR_KEY'] == 'abc'`。
+#: 🔴 这是**白名单**（不是黑名单）：想让块读一项，就给那个变量加这个前缀，不用改库的代码。
+#: ⚠️ 字面量的真源在 `sdk`（上面那行 import）—— 这里**不许**再写一遍 `'BLOCK_'`。
+
+#: `.env` 里一行的形状。允许 `export` 前缀、行首缩进、`=` 两边空白；
+#: 🔴 **不剥行内注释**（值里真带 `#` 的密钥不该被截断）、**不做变量展开**（那会让"谁先谁后"变成隐式规则）。
+_ENV_LINE = re.compile(r'^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$')
+
+
+def load_env_file(path: str | Path) -> None:
+    """把一份 `.env` 并进 `os.environ`（在 `settings.py` 的**第一行**调一次）。
+
+    🔴 必须排在读 `os.environ` 之前：顺序反了，`.env` 里给的值读不到，
+       而报出来的症状是"我配了，它还是不生效"。
+    🔴 `.env` **覆盖**进程环境：它是项目的配置真源，而进程里可能留着同名的外部变量。
+    🔴 用 `utf-8-sig` 读：编辑器存"UTF-8 带 BOM"时那个 BOM 会粘在第一个键名前面，
+       而 `^\\s*` 不匹配它 ⇒ 第一行**静默消失**（症状是"我明明配了它"）。
+    ⚠️ 文件不在 = 什么都不做（不抛、不报）：缺配置该由**用到它的那一刻**报出来。
+    """
+    source = Path(path)
+    if not source.is_file():
+        return
+    values: dict[str, str] = {}
+    for line in source.read_text(encoding='utf-8-sig').splitlines():
+        match = _ENV_LINE.match(line)
+        if not match:
+            continue  # 空行与 `#` 注释都走这一条
+        raw = match.group(2).strip()
+        quoted = len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ('"', "'")
+        values[match.group(1)] = raw[1:-1] if quoted else raw
+    os.environ.update(values)
+
+
+def read_env(name: str) -> str:
+    """读一个环境变量（空串当没写 —— `.env` 里 `KEY=` 是常态），去掉首尾空白。"""
+    return str(os.environ.get(name, '') or '').strip()
+
+
+def block_config(env: Mapping[str, str] | None = None) -> dict[str, str]:
+    """给块的配置：带 `BLOCK_` 前缀的那几个，**剥掉前缀当键**。
+
+    🔴 没配的键在 `ctx.config` 上**不存在**（别拿 `None` 当默认值使，先判 `'X' in ctx.config`）；
+       配成空串的**照给**（`BLOCK_X=` ⇒ `ctx.config['X'] == ''`）。
+    🔴 剥完是空串的**不算键**（`BLOCK_=` 不可能是名字）。
+    🔴 别的变量一个都不给块 —— 数据库连接串、SSO 密钥都不在这里。
+    """
+    source = os.environ if env is None else env
+    result: dict[str, str] = {}
+    for name, value in source.items():
+        if not name.startswith(BLOCK_CONFIG_PREFIX):
+            continue
+        key = name[len(BLOCK_CONFIG_PREFIX):]
+        if key:
+            result[key] = value
+    return result
+
+
+# ──────────────────────────── "有哪几个环境变量"这份清单 ────────────────────────────
+
+#: 登录那一组的组名。🔴 `auth/sso.py` 按它取必填清单（**不抄第二份名单**）。
+LOGIN_GROUP = '登录（Authing OIDC）'
+
+
+@dataclass(frozen=True)
+class EnvItem:
+    """一个环境变量在**开发包**里被看到的样子。
+
+    🔴 `hint` 是"能直接粘进 `.env` 的一行"：缺必填时那句报错就照它说（见 `auth/sso.py`）——
+       只说"缺了"的报错，用户还得自己去翻文档才知道那一行该怎么写。
+    🔴 **这里永远不写值**：这份清单会铺进开发包（跟着块作者的编辑器走），而环境里有
+       数据库连接串与登录密钥。块的配置面是白名单，同一个道理。
+    """
+
+    #: 变量名。⚠️ 前缀那一条写的是 `BLOCK_*` —— 它不是一个真名字，是一族名字的前缀。
+    name: str
+    #: 这个变量管什么（一句人话）。
+    brief: str
+    #: 能直接粘进 `.env` 的一行（没有例子就是空串）。
+    hint: str = ''
+    #: 必填吗（缺了就跑不起来的那几项）。
+    required: bool = False
+    #: 分组（开发包里按它分段；"哪几项是登录用的"也从这里取）。
+    group: str = '平台'
+
+
+#: 平台读的**全部**环境变量 —— 唯一真源。
+#:
+#: 🔴 它是一份**清单**，不是"读值的入口"：各处仍然各读各的（`read_env('DATABASE_URL')` 之类）。
+#:    两者对不上的风险由 `tools/sdk-check-py.mjs` 兜住：它扫一遍库里所有 `read_env('<名字>')`
+#:    字面量，漏在这份清单外的当场报红。
+ENV_ITEMS: tuple[EnvItem, ...] = (
+    # ── 登录（Authing OIDC）：这四项不配就没人能登录 ──
+    EnvItem(
+        name='SSO_ISSUER',
+        brief='Authing 的 OIDC 发证地址（OIDC discovery 就在它下面）',
+        hint='SSO_ISSUER=https://<你的域名>.authing.cn/oidc',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_CLIENT_ID',
+        brief='Authing 应用的 App ID',
+        hint='SSO_CLIENT_ID=<Authing 应用的 App ID>',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_CLIENT_SECRET',
+        brief='Authing 应用的 App Secret（**只在服务端**用，别带进前端）',
+        hint='SSO_CLIENT_SECRET=<Authing 应用的 App Secret>',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_REDIRECT_URI',
+        brief='登录回调地址（必须与 Authing 应用里登记的那个逐字一致）',
+        hint='SSO_REDIRECT_URI=http://localhost:8000/auth/callback',
+        required=True,
+        group=LOGIN_GROUP,
+    ),
+    EnvItem(
+        name='SSO_WEB_ORIGIN',
+        brief='登录成功后把人送回哪个前端地址（不写就用 auth/sso.py 里的默认值）',
+        hint='SSO_WEB_ORIGIN=http://localhost:5173',
+        group=LOGIN_GROUP,
+    ),
+    # ── 跨源与数据库 ──
+    EnvItem(
+        name='CORS_ORIGIN',
+        brief='允许跨源访问的前端地址（逗号分隔）；它同时是 CSRF 信任名单的来源',
+        hint='CORS_ORIGIN=http://localhost:5173',
+        group='跨源与数据库',
+    ),
+    EnvItem(
+        name='DATABASE_URL',
+        brief='项目数据库连接串（postgres://… 形式）；不写就用项目自己 settings 里的 DATABASES',
+        hint='DATABASE_URL=postgres://user:password@127.0.0.1:5432/app',
+        group='跨源与数据库',
+    ),
+    # ── 平台开关 ──
+    EnvItem(
+        name='BOOTSTRAP_ADMIN_WORK_IDS',
+        brief='管理员名单：启动时把这些人设成 is_staff，名单之外的一律清掉（逗号分隔，上限 200；没配就是没有管理员）',
+        hint='BOOTSTRAP_ADMIN_WORK_IDS=1001',
+        group='平台开关',
+    ),
+    EnvItem(
+        name='LABULL_SCHEMA_CANVAS',
+        brief='数据模型那一页的开关：on 常开 / auto 只在 DEBUG 开 / 其余（默认）不开',
+        hint='LABULL_SCHEMA_CANVAS=on',
+        group='平台开关',
+    ),
+    EnvItem(
+        name='LABULL_CONTRACT_PATH',
+        brief='模型形状那份 JSON 的落点（**兜底**用：画布的基线默认是从提交里的源码算的；默认 .labull/contract.json）',
+        hint='LABULL_CONTRACT_PATH=.labull/contract.json',
+        group='平台开关',
+    ),
+    EnvItem(
+        name='LABULL_BASELINE_REV',
+        brief="画布拿哪一版当\"上一版\"：留空＝HEAD~1（上一次提交改了什么）/ head＝只看没提交的改动 / off＝不做差异 / 也可以给一个提交号或分支",
+        hint='LABULL_BASELINE_REV=HEAD~1',
+        group='平台开关',
+    ),
+    EnvItem(
+        name='LABULL_BASELINE_IGNORE_APPS',
+        brief='画布比对时**不参与**的 app（逗号/空格分隔，例如 labull_framework）—— 这些 app 的表照样画，只是不带"上一版 vs 现在"的差异色',
+        hint='LABULL_BASELINE_IGNORE_APPS=labull_framework',
+        group='平台开关',
+    ),
+    # 🔴 下面两条是**体检**那一侧的应急开关（名字的真源在 `magic_block/sdk.py`，不在这里手抄）：
+    #    默认都开 —— 关掉等于"字段改名这类问题回到运行期才现形"，只该在排查误报时临时用一下。
+    EnvItem(
+        name=BLOCK_DEEPCHECK,
+        brief='块的「引用深检」总开关：off 退回只判形状（字段 / 模型改了名就不再提前报出来）',
+        hint=f'{BLOCK_DEEPCHECK}=off',
+        group='平台开关',
+    ),
+    # 🔴 依赖声明（`requires`）那一层的开关（名字的真源在 `magic_block/sdk.py`）：
+    #    默认 `error`（1.0.1 起）—— "先警告、后强制"里的**后强制**已经落地了。
+    #    ⚠️ 代价如实说：库里那些**还没声明**的存量块会集体判不合格（全部停用），
+    #       所以升级前先用 `manage.py labull_requires --write` 把扫得到的声明批量补进库
+    #       （那条命令就是为这个默认值而存在的：它是这条路上唯一的恢复口）。
+    EnvItem(
+        name=BLOCK_REQUIRES,
+        brief='块「依赖声明」（requires）那一层的开关：off 整段不跑 / warn 只提示不拦（要显式写）/ error（默认）变成硬判据',
+        hint=f'{BLOCK_REQUIRES}=warn',
+        group='平台开关',
+    ),
+    # 🔴 块「类型」那一层的开关（名字的真源在 `magic_block/sdk.py`）：
+    #    默认 `error`（与 `requires` 同一个方向）—— 声明了 `type: workflow` 却写错流程，那是事实。
+    #    ⚠️ `off` 只关"这一种类型多出来的判据"，通用那几段**一直跑**（V7 盯着这一条）。
+    EnvItem(
+        name=BLOCK_TYPE,
+        brief='块「类型」（清单里的 type）那一层的开关：off 只关该类型多出来的判据（通用校验照跑）/ warn 只提示不拦 / error（默认）变成硬判据',
+        hint=f'{BLOCK_TYPE}=warn',
+        group='平台开关',
+    ),
+    # 🔴 体检那条链一次开几个口子（名字的真源在 `magic_block/parallel.py` 的 `ENV_WORKERS`）。
+    #    ⚠️ 它是**性能旋钮、不是判据**：写错一个数（0 / 64 / 一句乱码）会被夹到 1..8，不该让体检报错。
+    #    它在这里的意义是"使用者的清单里能看见这个开关"（`backend.lock.pyi` 就是按 ENV_ITEMS 铺的）。
+    EnvItem(
+        name='LABULL_BLOCK_WORKERS',
+        brief='启动体检 / 全量校验一次开几个子进程（默认 4，夹在 1..8）：机器小就往下调，写 1 退回串行',
+        hint='LABULL_BLOCK_WORKERS=2',
+        group='平台开关',
+    ),
+    # ── 块的配置面 ──
+    EnvItem(
+        name=f'{BLOCK_CONFIG_PREFIX}*',
+        brief='块的配置面：**只有**带这个前缀的变量才进 ctx.config（前缀剥掉当键，别的变量一个都不给块）',
+        hint=f'{BLOCK_CONFIG_PREFIX}OCR_KEY=xxx',
+        group='块的配置',
+    ),
+)
+
+
+def required_items(group: str) -> tuple[EnvItem, ...]:
+    """某一组里必填的那几项（顺序 = `ENV_ITEMS` 里的顺序，所以报错顺序稳定）。"""
+    return tuple(item for item in ENV_ITEMS if item.group == group and item.required)