cckit 0.1.0__py3-none-any.whl

cckit/lint.py

@@ -0,0 +1,309 @@
+"""kit 的 lint 检查。
+
+覆盖:skill 名合法性(小写 kebab-case、Windows 保留名、仅大小写不同的重名、
+synced 保留)、description 质量(缺失=error、含触发条件=warn、超 1536=warn、
+与已装 skill 语义重叠=warn)、CRLF 检查、prompt injection 启发式扫描
+(07 第 6 条)、依赖 typosquatting 提示(07 第 7 条)。
+
+全部是确定性的启发式,不调 LLM。返回 LintMessage 列表,级别 error / warn。
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import manifest
+
+# Windows 保留名(大小写不敏感)
+WINDOWS_RESERVED = {
+    "con", "prn", "aux", "nul",
+    *[f"com{i}" for i in range(1, 10)],
+    *[f"lpt{i}" for i in range(1, 10)],
+}
+SYNCED_RESERVED = "synced"
+
+# description 触发条件(启发式)
+_TRIGGER_RE = re.compile(
+    r"(?i)\b(use\s+when|use\s+this\s+(when|if|for)|when\s+(the\s+)?user\s|"
+    r"whenever|trigger\s|触发|使用时机|适用于)\b"
+)
+
+# prompt injection 启发式(07 第 6 条)。定位是警告,不是可靠防护。
+_PROMPT_INJECTION = [
+    (re.compile(r"(?i)ignore\s+(all\s+)?(previous|prior|above|earlier)\s+instructions"),
+     "要求忽略既有指令"),
+    (re.compile(r"(?i)\byou\s+are\s+now\b"), "尝试重新定义助手角色"),
+    (re.compile(r"(?i)(cat|read|print|get|open)\s+[`'\"]?\.?env\b"), "要求读取 .env 文件"),
+    (re.compile(r"(?i)(id_rsa|ssh[_-]?key|private[_\s]?key|authorized_keys)"),
+     "要求访问 SSH 私钥"),
+    (re.compile(r"(?i)(curl|wget|fetch|http)\b.{0,80}(--data|-d\s|POST|upload|exfiltrate)"),
+     "疑似向外部地址发送数据"),
+]
+
+# 知名 PyPI 包,用于 typosquatting 提示(启发式,非全量)
+_KNOWN_PYPI = {
+    "requests", "numpy", "pandas", "scipy", "matplotlib", "flask", "django",
+    "fastapi", "uvicorn", "httpx", "aiohttp", "beautifulsoup4", "lxml",
+    "urllib3", "certifi", "idna", "charset-normalizer", "pyyaml", "pytest",
+    "pydantic", "sqlalchemy", "click", "jinja2", "pillow", "opencv-python",
+    "scikit-learn", "tensorflow", "torch", "tqdm", "rich", "typer",
+}
+
+# 知名 npm 包,用于 package.json 依赖的 typosquatting 提示(启发式,非全量)
+_KNOWN_NPM = {
+    "express", "lodash", "react", "react-dom", "axios", "chalk", "commander",
+    "debug", "dotenv", "fs-extra", "inquirer", "minimist", "moment",
+    "node-fetch", "typescript", "webpack", "eslint", "prettier", "jest",
+    "yargs", "glob", "semver", "uuid", "winston", "zod", "next", "vue",
+    "mongoose", "socket.io",
+}
+
+_STOP = {
+    "the", "and", "for", "you", "this", "that", "with", "from", "your",
+    "when", "will", "not", "are", "use", "into", "can", "its", "have",
+    "has", "was", "were", "been", "being", "they", "them", "their", "then",
+}
+
+
+@dataclass
+class LintMessage:
+    level: str      # 'error' | 'warn'
+    message: str
+
+class LintKit:
+    def __init__(self, kit_dir: Path, data: dict, installed_descs: list[str] | None = None):
+        self.kit_dir = kit_dir
+        self.data = data
+        self.installed_descs = installed_descs or []
+
+    @staticmethod
+    def _skill_desc(skill_dir: Path) -> tuple[str, str]:
+        fm = manifest.read_skill_frontmatter(skill_dir)
+        return (str(fm.get("description") or ""), str(fm.get("when_to_use") or ""))
+
+    def _lint_skill_names(self) -> list[LintMessage]:
+        """skill 名合法性:Windows 保留名、synced 保留、仅大小写不同的重名。
+
+        大写检查不在这里 —— add 路径先过 schema(slug pattern 只允许小写),此处
+        再查是死代码且误导读者(见 M9)。这里只留 schema 之外才可能出现的约束。
+        """
+        msgs: list[LintMessage] = []
+        names = [sk["name"] for sk in self.data.get("skills", [])]
+        by_lower: dict[str, list[str]] = {}
+        for n in names:
+            ln = n.lower()
+            if ln in WINDOWS_RESERVED:
+                msgs.append(LintMessage("error", f"skill 名 {n!r} 是 Windows 保留名"))
+            if ln == SYNCED_RESERVED:
+                msgs.append(LintMessage("error", f"skill 名 {n!r} 是 CC 保留目录名 synced"))
+            by_lower.setdefault(ln, []).append(n)
+        for ln, lst in by_lower.items():
+            if len(lst) > 1:
+                msgs.append(LintMessage("error", f"仅大小写不同的重名 skill: {lst}"))
+        return msgs
+
+    def _lint_descriptions(self) -> list[LintMessage]:
+        msgs: list[LintMessage] = []
+        for sk in self.data.get("skills", []):
+            desc, when = self._skill_desc(self.kit_dir / sk["name"])
+            if not desc.strip():
+                msgs.append(LintMessage(
+                    "error", f"skill {sk['name']!r} 的 description 缺失(CC 靠它选工具)"))
+                continue
+            if _TRIGGER_RE.search(desc):
+                msgs.append(LintMessage(
+                    "warn",
+                    f"skill {sk['name']!r} 的 description 含触发条件(如 'Use when...'),"
+                    f"应移到 when_to_use"))
+            total = len(desc) + len(when)
+            if total > 1536:
+                msgs.append(LintMessage(
+                    "warn",
+                    f"skill {sk['name']!r} description+when_to_use 共 {total} 字符,"
+                    f"超过 1536 会被 CC 截断"))
+            for other in self.installed_descs:
+                if TextSimilarity(desc, other).similarity() > 0.9:
+                    msgs.append(LintMessage(
+                        "warn",
+                        f"skill {sk['name']!r} 的 description 与已装 skill 语义重叠"
+                        f"(CC 可能挑错工具)"))
+                    break
+        return msgs
+
+    def _lint_crlf(self) -> list[LintMessage]:
+        return CRLFLint(self.kit_dir).lint_crlf()
+
+    def _lint_prompt_injection(self) -> list[LintMessage]:
+        msgs: list[LintMessage] = []
+        for sk in self.data.get("skills", []):
+            md = self.kit_dir / sk["name"] / "SKILL.md"
+            if not md.is_file():
+                continue
+            text = md.read_text(encoding="utf-8", errors="replace")
+            for pat, desc in _PROMPT_INJECTION:
+                if pat.search(text):
+                    msgs.append(LintMessage(
+                        "warn",
+                        f"skill {sk['name']!r} 的 SKILL.md 疑似 prompt injection:{desc}"))
+                    break
+        return msgs
+
+    def _lint_typosquatting(self) -> list[LintMessage]:
+        return TyposquatLint(self.kit_dir, self.data).lint_typosquatting()
+
+    def lint_kit(self) -> list[LintMessage]:
+        """对一个已通过 schema 校验的 kit 做全部 lint。"""
+        msgs: list[LintMessage] = []
+        msgs += self._lint_skill_names()
+        msgs += self._lint_descriptions()
+        msgs += self._lint_crlf()
+        msgs += self._lint_prompt_injection()
+        msgs += self._lint_typosquatting()
+        return msgs
+
+
+class TextSimilarity:
+    """文本相似度计算,用于 description 语义重叠提示。
+
+    目前用简单的 token 集交集/并集比值,不调 LLM (基于 token 集合的 Jaccard 相似度)。token 是小写拉丁字母数字
+    序列(长度>2)与 CJK 字符(单字+双字 bi-gram),停用词过滤掉。
+    """
+    def __init__(self, a: str, b: str):
+        self.a = a
+        self.b = b
+
+    @staticmethod
+    def _tokens(text: str) -> set[str]:
+        s = text.lower()
+        latin = {w for w in re.findall(r"[a-z0-9]{3,}", s) if w not in _STOP}
+        cjk = re.findall(r"[一-鿿]", s)
+        cjk_bi = {cjk[i] + cjk[i + 1] for i in range(len(cjk) - 1)}
+        return latin | set(cjk) | cjk_bi
+
+    def similarity(self) -> float:
+        ta, tb = self._tokens(self.a), self._tokens(self.b)
+        if not ta or not tb:
+            return 0.0
+        return len(ta & tb) / len(ta | tb)
+
+
+class CRLFLint:
+    """检查 kit 内文本文件是否含 CRLF 换行,在 Linux 上 .sh 会 bad interpreter。"""
+    def __init__(self, kit_dir: Path):
+        self.kit_dir = kit_dir
+
+    def _text_files(self) -> list[Path]:
+        skip = {".git", "__pycache__", ".venv", "node_modules"}
+        out: list[Path] = []
+        for f in self.kit_dir.rglob("*"):
+            if not f.is_file():
+                continue
+            if any(part in skip for part in f.parts):
+                continue
+            if f.stat().st_size > 1_000_000:
+                continue
+            out.append(f)
+        return out
+
+    def lint_crlf(self) -> list[LintMessage]:
+        msgs: list[LintMessage] = []
+        for f in self._text_files():
+            try:
+                raw = f.read_bytes()
+            except OSError:
+                continue
+            if b"\r\n" in raw:
+                rel = f.relative_to(self.kit_dir)
+                msgs.append(LintMessage(
+                    "warn",
+                    f"{rel} 含 CRLF 换行,在 Linux 上 .sh 会 bad interpreter,建议转 LF"))
+        return msgs
+
+
+class TyposquatLint:
+    """检查 kit 内依赖是否疑似 typosquatting,用于提示(07 第 7 条)。"""
+    def __init__(self, kit_dir: Path, data: dict):
+        self.kit_dir = kit_dir
+        self.data = data
+
+    def lint_typosquatting(self) -> list[LintMessage]:
+        """typosquatting 提示:requirements.txt(python)与 package.json(node)都扫。"""
+        msgs: list[LintMessage] = []
+        requires = self.data.get("requires") or {}
+        py_file = (requires.get("python") or {}).get("file")
+        if py_file:
+            req = self.kit_dir / py_file
+            if req.is_file():
+                msgs += self._typosquat_check(self._parse_requirements(req), _KNOWN_PYPI)
+        node_file = (requires.get("node") or {}).get("file")
+        if node_file:
+            pkg = self.kit_dir / node_file
+            if pkg.is_file():
+                msgs += self._typosquat_check(self._parse_package_names(pkg), _KNOWN_NPM)
+        return msgs
+
+    def _typosquat_check(self, names: list[str], known: set[str]) -> list[LintMessage]:
+        """对一组依赖名做 typosquatting 提示(与 known 集比对)。"""
+        msgs: list[LintMessage] = []
+        for pkg in names:
+            name = pkg.lower()
+            if name in known:
+                continue
+            for k in known:
+                if abs(len(k) - len(name)) <= 1 and self._lev(name, k) <= 1:
+                    msgs.append(LintMessage(
+                        "warn",
+                        f"依赖 {pkg!r} 与知名包 {k!r} 极其相似,疑似 typosquatting"))
+                    break
+        return msgs
+
+    @staticmethod
+    def _parse_package_names(path: Path) -> list[str]:
+        """package.json 的 dependencies + devDependencies 键名。"""
+        try:
+            pkg = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return []
+        deps = {}
+        deps.update(pkg.get("dependencies") or {})
+        deps.update(pkg.get("devDependencies") or {})
+        return list(deps.keys())
+
+    @staticmethod
+    def _parse_requirements(path: Path) -> list[str]:
+        names: list[str] = []
+        for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or line.startswith("-"):
+                continue
+            m = re.match(r"^[A-Za-z0-9_.-]+", line)
+            if m:
+                names.append(m.group(0))
+        return names
+
+    @staticmethod
+    def _lev(a: str, b: str) -> int:
+        """Damerau-Levenshtein 距离(相邻换位计 1),用于 typosquatting 提示。
+
+        用普通 Levenshtein 会把 'reqeusts'(换位)→ 'requests' 算成 2,漏掉最常见的
+        手误。相邻换位算 1 才能命中 Docs/07 第 7 条给的示例。
+        """
+        if not a:
+            return len(b)
+        if not b:
+            return len(a)
+        la, lb = len(a), len(b)
+        d = [[0] * (lb + 1) for _ in range(la + 1)]
+        for i in range(la + 1):
+            d[i][0] = i
+        for j in range(lb + 1):
+            d[0][j] = j
+        for i in range(1, la + 1):
+            for j in range(1, lb + 1):
+                cost = 0 if a[i - 1] == b[j - 1] else 1
+                d[i][j] = min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost)
+                if i > 1 and j > 1 and a[i - 1] == b[j - 2] and a[i - 2] == b[j - 1]:
+                    d[i][j] = min(d[i][j], d[i - 2][j - 2] + 1)
+        return d[la][lb]

cckit/manifest.py

@@ -0,0 +1,113 @@
+"""cckit.yaml 的加载与校验。
+
+三步:存在性检查 → yaml.safe_load → JSON Schema 校验 → 语义检查
+(needs 引用、skill 目录与 skills[] 一致、platforms 匹配当前平台、依赖文件存在)。
+没有 cckit.yaml 直接拒绝 —— 这是"合法 kit"的唯一判据(见 Docs/03)。
+
+另外提供 SKILL.md frontmatter 的读取(供 lint / state 读 description)。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from . import config, schema
+from .errors import CckitError
+
+
+class ManifestError(CckitError):
+    """cckit.yaml 不合法。"""
+
+
+def load(manifest_path: Path) -> dict:
+    """读 cckit.yaml;没有它直接拒绝。"""
+    if not manifest_path.exists():
+        raise ManifestError(f"找不到 cckit.yaml: {manifest_path}(没有它,cckit 拒绝安装)")
+    try:
+        with open(manifest_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ManifestError(f"cckit.yaml 解析失败: {e}")
+    if not isinstance(data, dict):
+        raise ManifestError("cckit.yaml 顶层必须是 mapping")
+    return data
+
+
+def validate_schema(data: dict) -> None:
+    """JSON Schema 校验(Draft 2020-12),一次报出全部错误。"""
+    errors = sorted(schema.validator().iter_errors(data), key=lambda e: list(e.path))
+    if errors:
+        lines = [
+            "  - " + ("/".join(map(str, e.path)) or "(root)") + ": " + e.message
+            for e in errors
+        ]
+        raise ManifestError("cckit.yaml 未通过 JSON Schema 校验:\n" + "\n".join(lines))
+
+
+def semantic_check(data: dict, kit_dir: Path, platform: str | None = None) -> None:
+    """schema 之外的语义约束,涉及文件系统与当前平台。"""
+    platform = platform or config.platform_name()
+
+    # 1. 平台匹配:当前平台不在 platforms 内直接拒绝
+    plats = data.get("platforms")
+    if plats and platform not in plats:
+        raise ManifestError(f"当前平台 {platform} 不在 kit 声明的 platforms {plats} 中")
+
+    # 2. needs 引用:非 python/node 的值必须声明在 requires.system[].bin
+    # 注意:requires.system[].version / version_cmd 校验在 installer.py 的 compute_plan() 的 _check_system_version() 里做,这里不重复做
+    requires = data.get("requires") or {}
+    system_bins = {d.get("bin") for d in (requires.get("system") or [])}
+    for sk in data.get("skills", []):
+        for need in sk.get("needs", []):
+            if need in ("python", "node"):
+                continue
+            if need not in system_bins:
+                raise ManifestError(
+                    f"skill {sk['name']!r} 的 needs 引用了未声明的系统依赖 {need!r}")
+
+    # 3. 依赖文件存在性(requirements.txt / package.json)
+    for key in ("python", "node"):
+        fname = (requires.get(key) or {}).get("file")
+        if fname and not (kit_dir / fname).is_file():
+            raise ManifestError(f"requires.{key}.file 指向的文件不存在: {fname}")
+
+    # 4. skill 目录与 skills[] 一致
+    for sk in data.get("skills", []):
+        sdir = kit_dir / sk["name"]
+        if not sdir.is_dir():
+            raise ManifestError(f"skill {sk['name']!r} 缺少对应目录: {sdir}")
+        if not (sdir / "SKILL.md").is_file():
+            raise ManifestError(f"skill {sk['name']!r} 缺少 SKILL.md")
+
+    # 5. scripts[] 声明的脚本路径必须存在(相对 skill 目录,与 exec 白名单一致)
+    for sk in data.get("skills", []):
+        sdir = kit_dir / sk["name"]
+        for script in sk.get("scripts") or []:
+            if not (sdir / script).is_file():
+                raise ManifestError(
+                    f"skill {sk['name']!r} 声明的脚本不存在: {script}")
+
+
+def read_skill_frontmatter(skill_dir: Path) -> dict:
+    """读 skill 目录下 SKILL.md 的 YAML frontmatter,失败返回空 dict。"""
+    md = skill_dir / "SKILL.md"
+    if not md.is_file():
+        return {}
+    text = md.read_text(encoding="utf-8", errors="replace")
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    end = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end = i
+            break
+    if end is None:
+        return {}
+    fm = "\n".join(lines[1:end])
+    try:
+        data = yaml.safe_load(fm)
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}

cckit/registry.py

@@ -0,0 +1,136 @@
+"""registry.json 的读写。
+
+registry 只存"从文件系统观测不出来"的东西:kit 来源(URL/ref/sha)、版本、
+envs 路径映射(每个 skill 的 runtime → env_dir)、known_scopes。启用状态是派生的,不写这里(见 state.py)。
+写入必须原子(临时文件 + os.replace),避免半截 JSON。
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from . import config
+from .errors import CckitError
+
+
+def load() -> dict:
+    """读 registry;不存在时返回空结构;损坏时抛受检 CckitError(不静默、不裸 traceback)。"""
+    path = config.registry_path()
+    if not path.exists():
+        return {"version": 1, "kits": {}}
+    with open(path, encoding="utf-8") as f:
+        try:
+            data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise CckitError(f"registry.json 不是合法 JSON,已损坏: {e}") from e
+    if not isinstance(data, dict) or not isinstance(data.get("kits"), dict):
+        raise CckitError(f"registry.json 结构损坏: {path}")
+    data.setdefault("version", 1)
+    return data
+
+
+def save(data: dict) -> None:
+    """原子写:临时文件 + os.replace。"""
+    path = config.registry_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".registry-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def get_kit(name: str) -> dict | None:
+    """按 kit 名取记录,不存在返回 None。"""
+    return load().get("kits", {}).get(name)
+
+
+def add_kit(name: str, info: dict) -> None:
+    """新增或覆盖一个 kit 记录。"""
+    data = load()
+    data.setdefault("kits", {})[name] = info
+    save(data)
+
+
+def remove_kit(name: str) -> dict | None:
+    """删除一个 kit 记录,返回被删内容(不存在返回 None)。"""
+    data = load()
+    info = data.get("kits", {}).pop(name, None)
+    if info is not None:
+        save(data)
+    return info
+
+
+def add_override_scope(name: str, scope_value: str) -> None:
+    """把项目根追加进 kit 的 override_scopes(去重)。
+
+    override_scopes 记录"仅在项目级 override 过、无 link"的项目根,供 remove
+    清理 settings.local.json 的 skillOverrides 残留。它与 known_scopes 刻意分离:
+    known_scopes 表示"安装过",参与 find_skill / list_skills 的作用域定位;
+    override_scopes 表示"被项目覆盖过",若混入 known_scopes 会把全局 kit 误判成
+    项目 kit,进而污染 find_skill 消歧与 list_skills 的 installed 归属。
+    """
+    data = load()
+    info = data.get("kits", {}).get(name)
+    if info is None:
+        raise CckitError(f"kit {name!r} 不在 registry 中")
+    scopes = info.get("override_scopes")
+    if not isinstance(scopes, list):
+        scopes = []
+    if scope_value not in scopes:
+        scopes.append(scope_value)
+        info["override_scopes"] = scopes
+        save(data)
+
+
+def _kit_in_scope(info: dict, scope: str) -> bool:
+    """kit 的 known_scopes 是否包含给定作用域。
+
+    project 作用域按当前项目根路径比对(与 installer 写 known_scopes 时一致)。
+    """
+    scopes = info.get("known_scopes") or []
+    if scope == "global":
+        return "global" in scopes
+    root = config.project_root()
+    return root is not None and str(root) in scopes
+
+
+def find_skill_matches(name: str, scope: str | None = None) -> list[tuple[str, dict]]:
+    """返回所有匹配的 (kit, skill) 列表,不报错(0 或 >1 都原样返回)。
+
+    供 state.set_state 的项目作用域回退逻辑用:先找项目 kit,没有时再回退全局
+    kit —— 但必须保留"多个 kit 同名"的歧义,不能把它静默吞成"回退全局"。
+    """
+    matches: list[tuple[str, dict]] = []
+    for kit, info in load().get("kits", {}).items():
+        if scope is not None and not _kit_in_scope(info, scope):
+            continue
+        for sk in info.get("skills", []):
+            if sk.get("name") == name:
+                matches.append((kit, sk))
+    return matches
+
+
+def find_skill(name: str, scope: str | None = None) -> tuple[str, dict]:
+    """按 skill 名查找,要求唯一;0 或 >1 都报错。
+
+    scope 给定时("global"/"project")只在对应作用域内找 —— 同名 skill
+    全局与项目各装一份时,靠作用域即可唯一定位(见 Docs/04:所有命令默认
+    全局,`--project` 作用项目)。scope=None 时在全部 kit 里找。
+    """
+    matches = find_skill_matches(name, scope)
+    if not matches:
+        where = f"({scope} 作用域)" if scope else ""
+        raise CckitError(f"skill {name!r} 不在 registry 中{where}(不是 cckit 管理或未安装)")
+    if len(matches) > 1:
+        kits = ", ".join(k for k, _ in matches)
+        raise CckitError(f"skill {name!r} 在多个 kit 中出现({kits}),无法唯一定位")
+    return matches[0]

cckit/schema.py

@@ -0,0 +1,42 @@
+"""cckit.yaml 的 JSON Schema 加载器。
+
+schema 的源文件在 Docs/schema/cckit.schema.json;这里在包内保留一份副本
+(src/cckit/cckit.schema.json),运行时无需依赖文档目录。测试会校验两份一致。
+
+homepage 的 `format: uri` 用自定义 checker 校验(仅靠 stdlib urllib.parse)。
+jsonschema 自带的 uri checker 依赖可选的 rfc3987,未装时静默放行一切 ——
+等于没校验,所以这里显式实现一个宽松但有效的版本。
+"""
+from __future__ import annotations
+
+import json
+from importlib import resources
+from urllib.parse import urlparse
+
+from jsonschema import Draft202012Validator, FormatChecker
+
+
+def _is_uri(instance: object) -> bool:
+    """宽松但有效的 URI 校验:非空、无空白、有 scheme。"""
+    if not isinstance(instance, str) or not instance.strip():
+        return False
+    if any(ch.isspace() for ch in instance):
+        return False
+    try:
+        parsed = urlparse(instance)
+    except ValueError:
+        return False
+    return bool(parsed.scheme)
+
+
+def load() -> dict:
+    """读入 JSON Schema dict。"""
+    text = resources.files("cckit").joinpath("cckit.schema.json").read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+def validator() -> Draft202012Validator:
+    """构造一个 Draft 2020-12 校验器,带 format_checker 真正校验 homepage 的 uri。"""
+    checker = FormatChecker()
+    checker.checks("uri")(_is_uri)
+    return Draft202012Validator(load(), format_checker=checker)