dse-core 0.1.0__py3-none-any.whl

dse_core/__init__.py

@@ -0,0 +1,40 @@
+"""dse-core · 字典场景引擎（Python 版）—— 场景即字典，能力即插件。
+
+快速上手::
+
+    from dse_core import create_engine, play, inspect_project
+
+    play(root="./my-game")                  # 装配并跑完整局
+    ctx = create_engine(root="./my-game")   # 只装配，自行驱动主循环
+    inspect_project("./my-game")            # 只读体检
+
+Node/Cordis 版（姊妹仓库 dse-core）的移植；内容包为 YAML 数据文件，
+条件表达式走 AST 白名单求值（dse_core.safety）。
+"""
+
+from .runtime import Context, Service
+from .sdk import (
+    __version__,
+    analyze,
+    create_engine,
+    inspect_project,
+    load_dict,
+    load_packs,
+    load_project,
+    play,
+    scene_chars,
+)
+
+__all__ = [
+    "__version__",
+    "Context",
+    "Service",
+    "analyze",
+    "create_engine",
+    "inspect_project",
+    "load_dict",
+    "load_packs",
+    "load_project",
+    "play",
+    "scene_chars",
+]

dse_core/cli.py

@@ -0,0 +1,148 @@
+"""命令行 dse：play / scenes / info / check。
+
+移植自 dse-core(Node) cli.js 的 P1 子集（packs / new / doctor / saves
+属 P2）。约定：stdout 只放结果，诊断走 stderr；check 发现问题退出码 1。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__, graph
+from .loader import load_pack_file, load_project
+from .plugins.scenes import find_dangling, validate_scenes
+from .sdk import inspect_project, load_dict, play
+from .schema import validate_pack
+
+
+def _print_banner() -> None:
+    title = f"字 典 场 景 引 擎  v{__version__}"
+    width = sum(2 if ord(ch) > 0x2E7F else 1 for ch in title)
+    border = "═" * 40
+    print(f"╔{border}╗")
+    print(f"║   {title}{' ' * max(0, 37 - width)}║")
+    print(f"║   Dictionary Scene Engine (Python){' ' * max(0, 37 - 32)}║")
+    print(f"╚{border}╝")
+
+
+def _resolve_root(root: str | None) -> str:
+    """未指定 --root 时：当前目录有 dse.yml 就用它，否则用包内自带示例工程。"""
+    if root is not None:
+        return root
+    cwd = Path.cwd()
+    if (cwd / "dse.yml").is_file():
+        return str(cwd)
+    from .sdk import engine_root
+
+    return str(engine_root())
+
+
+def _cmd_play(args) -> int:
+    if args.input:
+        os.environ["DSE_INPUT"] = args.input
+    if args.banner:
+        _print_banner()
+    return play(root=args.root, entry=args.entry)
+
+
+def _cmd_scenes(args) -> int:
+    data = load_dict(args.root)
+    print(f"工程: {data['root']}（入口 {data['entry']}，内容包 {len(data['packFiles'])} 个）")
+    for scene_id in data["ids"]:
+        scene = data["dict"][scene_id]
+        mode = scene.get("mode") or "normal"
+        title = scene.get("title") or scene_id
+        n_choices = len(scene.get("choices") or [])
+        print(f"  {scene_id:<20} [{mode:<8}] {title}（{n_choices} 选项）")
+    print(f"共 {len(data['ids'])} 个场景")
+    return 0
+
+
+def _cmd_info(args) -> int:
+    report = inspect_project(args.root)
+    print(f"工程: {report['root']}")
+    print(f"入口: {report['entry']}")
+    print(f"场景: {report['scenes']} | 结局: {report['endings']}（可达 {report['endingsReachable']}）")
+    print(f"内容包: {', '.join(report['packFiles']) or '（无）'}")
+    for m in report["packs"]:
+        print(f"  - {m['id']} v{m['version']}《{m['name']}》 {m['scenes']} 场景 modes={m['modes']}")
+    if report["dangling"]:
+        print("悬空跳转:", file=sys.stderr)
+        for d in report["dangling"]:
+            print(f"  - {d['from']} -> {d['to']} ({d['kind']})", file=sys.stderr)
+    if report["unreachable"]:
+        print(f"警告: 不可达场景 {', '.join(report['unreachable'])}", file=sys.stderr)
+    return 0
+
+
+def _cmd_check(args) -> int:
+    root = Path(args.root)
+    problems: list[str] = []
+    try:
+        project = load_project(root)
+    except Exception as exc:  # noqa: BLE001 — 加载失败本身就是 check 的结论
+        print(f"[check] 工程加载失败: {exc}", file=sys.stderr)
+        return 1
+
+    # 1. Schema + 结构校验（逐内容包）
+    for rel in project.pack_files:
+        path = (root / rel).resolve()
+        _, scenes = load_pack_file(path)
+        problems += validate_pack(scenes, source=rel)
+        problems += validate_scenes(scenes, rel)
+
+    # 2. 悬空跳转
+    problems += find_dangling(project.dict)
+
+    # 3. 图分析（不可达仅警告，不判失败）
+    report = graph.analyze(project.dict, project.entry)
+
+    if problems:
+        print(f"[check] 发现 {len(problems)} 个问题:", file=sys.stderr)
+        for p in problems:
+            print(p, file=sys.stderr)
+        return 1
+    print(f"[check] 通过：{report['scenes']} 场景 / {len(report['endings'])} 结局（可达 {len(report['endingsReachable'])}）")
+    if report["unreachable"]:
+        print(f"警告: 不可达场景 {', '.join(report['unreachable'])}", file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="dse",
+        description="字典场景引擎 CLI —— 场景即字典，能力即插件",
+    )
+    parser.add_argument("--version", action="version", version=f"dse-core {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_play = sub.add_parser("play", help="开始游戏")
+    p_play.add_argument("--root", default=None, help="工程根目录（含 dse.yml）；缺省：当前目录有则用，否则用包内示例")
+    p_play.add_argument("--entry", help="覆盖入口场景 ID")
+    p_play.add_argument("--input", help='脚本输入序列，逗号分隔（如 "1,1,a,a"），用尽自动退出')
+    p_play.add_argument("--banner", action="store_true", help="打印启动横幅")
+    p_play.set_defaults(func=_cmd_play)
+
+    for name, help_text, func in (
+        ("scenes", "列出全部场景", _cmd_scenes),
+        ("info", "工程体检（结局/悬空/不可达）", _cmd_info),
+        ("check", "校验内容（Schema/悬空），有问题退出码 1", _cmd_check),
+    ):
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("--root", default=None, help="工程根目录（含 dse.yml）；缺省：当前目录有则用，否则用包内示例")
+        p.set_defaults(func=func)
+
+    args = parser.parse_args(argv)
+    args.root = _resolve_root(args.root)
+    try:
+        return args.func(args)
+    except (FileNotFoundError, ValueError, KeyError) as exc:
+        print(f"[dse] {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dse_core/example/content/starter.yml

@@ -0,0 +1,79 @@
+# 内容包：starter（P1 · 战斗线最小可玩版）
+#
+# 定位与 Node 版 starter.js 相同：骨架演示，不是游戏 —— 让新同学读完这
+# 一个文件就知道内容包能写什么。P1 覆盖 normal / battle 两种模式与
+# @restart；trade / dialogue / diary 线随 P3 能力插件补齐后迁入。
+pack:
+  id: starter
+  name: 启程 · 山道
+  version: 0.1.0
+  entry: start
+  description: P1 示例：一条跑通 normal/battle/结局/@restart 的最小可玩线路
+  author: dse-core
+  modes: [battle]
+  requires:
+    plugins: [combat]
+    state: [gold, hp, atk]
+
+scenes:
+  # ── 枢纽：进山，或回屋 ──────────────────────────────────────
+  start:
+    title: 村口 · 启程
+    text: 天没亮透，土路泛着潮气。你背上行囊，你娘把最后一包干粮塞进侧袋，手在包袱上按了按，没说话。往北是山，山里有过狼；身后是自家那扇还没上漆的木门。
+    choices:
+      - text: 往北进山
+        do: { 'flags.starter.mountain': true }
+        goto: forest
+      - text: 回屋，今天不出门
+        goto: inn-wait
+
+  # ── 战斗线：normal → battle ─────────────────────────────────
+  forest:
+    title: 山道 · 林深处
+    text: 松针压了一路，越往里越静。走到半坡，风忽然停了，林子里只剩你自己的脚步声。前面的灌木动了一下——一只独眼狼从阴影里站起来，耳朵贴着背，喉咙里滚着低音。它挡的是唯一的路。腰间那柄锈剑冰凉。
+    choices:
+      - text: 拔剑
+        goto: wolf-fight
+      - text: 握着剑柄，慢慢退回去
+        do: { 'flags.starter.fled': true }
+        goto: start
+
+  wolf-fight:
+    title: 山道 · 遭遇
+    text: 狼绕着你走了半圈，那只独眼始终盯着你的右手，没有眨过。你想起村里老猎户的话：它看的不是你的人，是你什么时候先动。于是你也不动，任由汗从额头滑到下巴，等它先犯错。
+    mode: battle
+    battle: { enemy: wolf, onWin: forest-win, onLose: forest-lose, onFlee: start }
+
+  forest-win:
+    title: 山道 · 狼倒下之后
+    text: 狼倒在松针上，血把针叶黏成一团，慢慢不再起伏。你喘了很久才直起腰。狼窝旁边压着一只旧木匣，里头是一枚生锈的渡口令牌。顺着狼来的方向往下走，能听见水声——但雾太浓，今天过不了河。
+    onEnter: { 'items.token': +1, 'flags.starter.wolfWin': true }
+    choices:
+      - text: 揣好令牌，回村
+        do: { 'flags.starter.backHome': true }
+        goto: start
+      - text: 力气还够，在林间再过一夜
+        if: 'hp >= 10'
+        goto: end-hero
+
+  forest-lose:
+    title: 结局 · 山道无归
+    text: 你倒下的时候，最后看见的是松针间漏下来的那点天光。狼没有立刻动口，它先闻了闻你的手——那手上什么也没有。这山上从此多了一条不该走的道，可每年还是有人走，因为每个人都觉得自己跟别人不一样。
+    choices:
+      - text: 再来一次
+        goto: '@restart'
+
+  # ── 结局 ────────────────────────────────────────────────────
+  end-hero:
+    title: 结局 · 过河的人
+    text: 你在林间生了一堆火。令牌在怀里，锈迹被体温焐得温热。河那头有什么你不知道，但你知道自己是从哪边过来的——这就够了。
+    choices:
+      - text: 再来一次
+        goto: '@restart'
+
+  inn-wait:
+    title: 结局 · 留在岸这边
+    text: 你回了屋，把门关上。路还摆在那儿，明天还在——你这样想，然后就睡着了。有些山，是不用过的。
+    choices:
+      - text: 再来一次
+        goto: '@restart'

dse_core/example/dse.yml

@@ -0,0 +1,64 @@
+# 字典场景引擎内核（dse-core）· 插件清单（Python 版）
+#
+# 与内容仓库的关系：本文件是**引擎默认开发配置**，只挂自带示例内容包
+# （content/starter.yml）。真正的项目应在自己的仓库里放一份 dse.yml，
+# 指向自己的内容包与数值表 —— 引擎代码一行都不用改。
+#
+# 依赖由运行时按 inject 声明拓扑编排：全部就绪后才会 setup。
+#
+# 插件分层：
+#   内核层  scenes / state / io / engine     引擎不可拔的四个基础服务
+#   能力层  combat                           接管 scene.mode 的可选玩法
+#          （P3 补 trade / dialogue / diary）
+
+# ── 内核层 ──────────────────────────────────────────────────────
+- id: scenes
+  config:
+    packs:                       # 内容包列表（后者覆盖前者同 ID 场景）
+      - ./content/starter.yml    # 引擎自带示例；换成自己的内容包即可
+
+- id: state
+  config:
+    # 时间循环保留域：goto '@loop:<场景>' 时保留这些前缀下的知识，
+    # 其余状态回 initial（"知识跨轮保留、消耗态每轮复原"）
+    loopKeep:
+      - clues.loop
+      - flags.loop
+    # 玩家初始状态。内容包用到的顶层字段必须在这里预声明，
+    # 否则条件表达式求值时报 NameError（dse check 会拦下）
+    initial:
+      name: 旅人
+      hp: 20
+      maxHp: 20
+      atk: 3                     # 基础攻击（+ 武器加成 = 实际 ATK）
+      def: 2                     # 防御（每点抵消 defenseFactor 点伤害）
+      crit: 0.15                 # 暴击率
+      gold: 20
+      items: {}
+      flags:
+        loop: {}                 # 时间循环中间层（预声明，条件链才不抛错）
+      clues:
+        loop: {}                 # 时间循环跨轮知识（loopKeep 保留域）
+
+- id: io
+
+- id: engine
+  config:
+    entry: start                 # 入场场景 ID（可用 DSE_ENTRY / --entry 覆盖）
+    prompt: '>> '
+
+# ── 能力层（每种能力接管一种 scene.mode）────────────────────────
+- id: combat
+  config:
+    formula:                     # 数值公式参数（可选，覆盖默认值）
+      variance: 0.2              # 伤害随机波动 ±20%
+      defenseFactor: 0.5         # 每点防御抵消的伤害
+      critMult: 1.8              # 暴击倍率
+      defendCut: 0.5             # 防御姿态减伤 50%
+      fleeChance: 0.45           # 逃跑成功率
+    weapons:                     # 武器加成（按背包数量累加到玩家 ATK）
+      rusty_sword:   { name: 锈剑, atk: 4 }
+      silver_dagger: { name: 银匕首, atk: 3 }
+    enemies:                     # 敌人字典（数据驱动，与场景字典同哲学）
+      wolf:   { name: 独眼狼, hp: 12, atk: 3, def: 0, crit: 0.10, drops: { gold: +5, 'items.wolf_pelt': +1 } }
+      bandit: { name: 沙盗,   hp: 14, atk: 3, def: 1, crit: 0.12, drops: { gold: +12 } }

dse_core/graph.py

@@ -0,0 +1,125 @@
+"""场景图分析（纯函数，不依赖运行时）。
+
+移植自 dse-core(Node) lib/graph.mjs：从「场景字典 + 入口」出发做静态图
+分析 —— 可达性、结局、悬空边、入度、深度、最短路径。引擎化之前这些逻辑
+散落在 lint 与测试里各写一份（BFS 口径还不一致），现在收敛到一处共用。
+"""
+
+from __future__ import annotations
+
+from .modes import is_special_goto, mode_edges, resolve_goto
+
+
+def is_ending(scene) -> bool:
+    """结局判定：normal 模式且无选项，或所有选项都是特殊目标（@restart 等）。"""
+    if not scene:
+        return False
+    if scene.get("mode") and scene["mode"] != "normal":
+        return False
+    choices = scene.get("choices") or []
+    return len(choices) == 0 or all(str(c.get("goto") or "").startswith("@") for c in choices)
+
+
+def edges_of(scene_id: str, scene) -> list[dict]:
+    """单个场景的全部出边（选项 goto + 模式流转边）。"""
+    out: list[dict] = []
+    for choice in (scene or {}).get("choices") or []:
+        raw = str(choice.get("goto") or "")
+        if not raw:
+            continue
+        target = resolve_goto(raw)
+        if not target or target.startswith("@"):
+            continue  # @restart 不参与可达
+        out.append({"from": scene_id, "to": target, "kind": "choice", "raw": raw})
+    mode = (scene or {}).get("mode") or "normal"
+    block = (scene or {}).get(mode) or {}
+    for key in mode_edges(mode):
+        target = block.get(key)
+        if target is not None:
+            out.append({"from": scene_id, "to": str(target), "kind": "mode", "raw": f"{mode}.{key}"})
+    return out
+
+
+def reachable_from(scenes: dict, entry: str) -> dict:
+    """从 entry 出发 BFS，返回 {reachable, order, depth}。
+
+    注意：Python 的 set 不保序，order 单独用列表记录（Node 的 Set 保插入序）。
+    """
+    reachable: set[str] = set()
+    order: list[str] = []
+    depth: dict[str, int] = {}
+    queue: list[tuple[str, int]] = [(entry, 0)]
+    while queue:
+        scene_id, d = queue.pop(0)
+        if scene_id in reachable or scene_id not in scenes:
+            continue
+        reachable.add(scene_id)
+        order.append(scene_id)
+        depth[scene_id] = d
+        for edge in edges_of(scene_id, scenes[scene_id]):
+            if edge["to"] not in reachable:
+                queue.append((edge["to"], d + 1))
+    return {"reachable": reachable, "order": order, "depth": depth}
+
+
+def analyze(scenes: dict, entry: str) -> dict:
+    """全图分析：可达性 + 悬空 + 结局 + 入度统计。"""
+    result = reachable_from(scenes, entry)
+    reachable, order, depth = result["reachable"], result["order"], result["depth"]
+    dangling: list[dict] = []
+    ending_ids: list[str] = []
+    in_degree: dict[str, int] = {}
+
+    for scene_id, scene in scenes.items():
+        if is_ending(scene):
+            ending_ids.append(scene_id)
+        for edge in edges_of(scene_id, scene):
+            in_degree[edge["to"]] = in_degree.get(edge["to"], 0) + 1
+            if edge["to"] not in scenes:
+                dangling.append(edge)
+        # 特殊目标自身的合法性（@loop: 目标必须存在）
+        for choice in (scene or {}).get("choices") or []:
+            raw = str(choice.get("goto") or "")
+            if raw.startswith("@") and not is_special_goto(raw):
+                dangling.append({"from": scene_id, "to": raw, "kind": "special", "raw": raw})
+            elif raw.startswith("@loop:"):
+                target = resolve_goto(raw)
+                if target not in scenes:
+                    dangling.append({"from": scene_id, "to": target, "kind": "loop", "raw": raw})
+
+    unreachable = [sid for sid in scenes if sid not in reachable]
+    return {
+        "scenes": len(scenes),
+        "reachable": reachable,
+        "reachableCount": len(reachable),
+        "unreachable": unreachable,
+        "order": order,
+        "depth": depth,
+        "dangling": dangling,
+        "endings": ending_ids,
+        "endingsReachable": [i for i in ending_ids if i in reachable],
+        "deadEnds": [sid for sid in order if in_degree.get(sid, 0) == 0 and sid != entry],
+    }
+
+
+def shortest_path(scenes: dict, entry: str, target_id: str) -> list[str] | None:
+    """从 entry 到指定场景的一条最短路径（供测试生成"直达路线"）。"""
+    prev: dict[str, str] = {}
+    queue = [entry]
+    seen = {entry}
+    while queue:
+        scene_id = queue.pop(0)
+        if scene_id == target_id:
+            break
+        for edge in edges_of(scene_id, scenes.get(scene_id)):
+            if edge["to"] in seen:
+                continue
+            seen.add(edge["to"])
+            prev[edge["to"]] = scene_id
+            queue.append(edge["to"])
+    if target_id not in seen:
+        return None
+    path = [target_id]
+    while path[0] != entry:
+        path.insert(0, prev.get(path[0]))
+    return path

dse_core/loader.py

@@ -0,0 +1,99 @@
+"""工程加载器：dse.yml + YAML 内容包 → 场景字典。
+
+移植自 dse-core(Node) lib/dict.mjs。与 Node 版的差异：内容包从 ESM
+模块改为 **YAML 数据文件**（pack 元数据 + scenes 字典同文件），因此不
+需要 import 任何用户代码。
+
+YAML 内容包结构::
+
+    pack: { id: starter, name: 启程, entry: start }   # 元数据（可选）
+    scenes:
+      start: { title: ..., text: ..., choices: [...] }
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .manifest import normalize_manifest
+
+
+@dataclass
+class LoadedProject:
+    """一个已加载的引擎工程（dse.yml + 全部内容包合并结果）。"""
+
+    root: Path
+    dict: dict                       # 合并后的场景字典（同 ID 后者覆盖前者）
+    ids: list                        # 场景 ID 列表（合并序）
+    pack_files: list                 # 内容包相对路径列表（顺序即覆盖优先级）
+    entry: str                       # 入口场景 ID
+    manifests: list = field(default_factory=list)  # 各内容包的规范化 manifest
+
+
+def load_yaml(path: str | Path) -> dict:
+    """读取 YAML 文件；空文件返回 {}。"""
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def read_plugin_config(manifest, plugin_id: str) -> dict:
+    """从 dse.yml 插件清单里取出指定 id 的 config（找不到返回 {}）。"""
+    entries = manifest if isinstance(manifest, list) else []
+    for item in entries:
+        if isinstance(item, dict) and item.get("id") == plugin_id:
+            return item.get("config") or {}
+    return {}
+
+
+def load_pack_file(path: str | Path) -> tuple[dict, dict]:
+    """读取一个 YAML 内容包 → (manifest_raw, scenes)。"""
+    data = load_yaml(path)
+    if not isinstance(data, dict):
+        raise ValueError(f"内容包 {path} 顶层必须是对象（pack / scenes 两个键）")
+    scenes = data.get("scenes") or {}
+    if not isinstance(scenes, dict):
+        raise ValueError(f"内容包 {path} 的 scenes 必须是「场景 ID → 场景定义」的对象")
+    return data.get("pack") or {}, scenes
+
+
+def load_project(root: str | Path) -> LoadedProject:
+    """加载整个工程：dse.yml + 全部内容包。"""
+    root = Path(root)
+    manifest = load_yaml(root / "dse.yml")
+    if not isinstance(manifest, list):
+        raise ValueError(f"{root / 'dse.yml'} 必须是插件条目列表")
+    scenes_cfg = read_plugin_config(manifest, "scenes")
+    engine_cfg = read_plugin_config(manifest, "engine")
+    pack_files = list(scenes_cfg.get("packs") or [])
+
+    merged: dict = {}
+    manifests = []
+    for rel in pack_files:
+        path = (root / rel).resolve()
+        if not path.is_file():
+            raise FileNotFoundError(f"内容包不存在: {rel}（相对于 {root}）")
+        raw, pack_scenes = load_pack_file(path)
+        manifests.append(normalize_manifest(raw, rel, pack_scenes))
+        merged.update(pack_scenes)  # 同 ID 后者覆盖前者（与 scenes 插件叠加语义一致）
+
+    return LoadedProject(
+        root=root,
+        dict=merged,
+        ids=list(merged.keys()),
+        pack_files=pack_files,
+        entry=engine_cfg.get("entry") or "start",
+        manifests=manifests,
+    )
+
+
+def scene_chars(scene: dict) -> int:
+    """场景正文长度（title + text + 各选项文本），与校验器口径一致。"""
+    choices = (scene or {}).get("choices") or []
+    return (
+        len((scene or {}).get("title") or "")
+        + len((scene or {}).get("text") or "")
+        + sum(len(c.get("text") or "") for c in choices)
+    )

dse_core/manifest.py

@@ -0,0 +1,76 @@
+"""内容包元数据（manifest）：规范化 / 校验。
+
+移植自 dse-core(Node) lib/registry.mjs 的纯逻辑部分（ESM 动态 import
+由 loader 接管，这里只保留 manifest 语义）。
+
+内容包约定（YAML，一个文件 = 一个包）::
+
+    pack:                        # 元数据（可选，缺省从文件推导）
+      id: starter
+      name: 启程
+      version: 0.1.0
+      entry: start               # 本包推荐入口（缺省取第一个场景）
+      modes: [battle]            # 用到了哪些 scene.mode
+      requires:
+        plugins: [combat]        # 需要哪些能力插件接管
+        state: [gold]            # 需要 state.initial 预声明哪些顶层字段
+    scenes:                      # 场景字典本体
+      start: { ... }
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .modes import mode_names
+
+_ID_RE = re.compile(r"^[a-z][a-z0-9_-]*$")
+_SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+")
+
+
+def strip_ext(file: str) -> str:
+    """取文件名去扩展名（manifest id 的缺省值）。"""
+    return Path(file).stem
+
+
+def normalize_manifest(raw: dict | None, file: str, scenes: dict | None = None) -> dict:
+    """补齐 manifest 缺省字段（id 取文件名，entry 取首个场景，modes 自动探测）。"""
+    raw = raw or {}
+    scenes = scenes or {}
+    ids = list(scenes.keys())
+    fallback_id = str(raw.get("id") or strip_ext(file))
+    modes = set(raw.get("modes") or [])
+    for scene in scenes.values():
+        if isinstance(scene, dict) and scene.get("mode"):
+            modes.add(scene["mode"])
+    return {
+        "id": fallback_id,
+        "name": raw.get("name") or fallback_id,
+        "version": raw.get("version") or "0.0.0",
+        "entry": raw.get("entry") or (ids[0] if ids else None),
+        "description": raw.get("description") or "",
+        "author": raw.get("author") or "",
+        "modes": sorted(modes),
+        "requires": {
+            "plugins": list((raw.get("requires") or {}).get("plugins") or []),
+            "state": list((raw.get("requires") or {}).get("state") or []),
+        },
+        "scenes": len(ids),
+    }
+
+
+def validate_manifest(manifest) -> list[str]:
+    """校验 manifest，返回问题列表（空列表 = 合法）。"""
+    if not isinstance(manifest, dict):
+        return ["manifest 不是对象"]
+    problems: list[str] = []
+    if not _ID_RE.match(str(manifest.get("id") or "")):
+        problems.append(f'id "{manifest.get("id")}" 不符合命名规范（小写字母开头，仅 a-z 0-9 _ -）')
+    if manifest.get("version") is not None and not _SEMVER_RE.match(str(manifest["version"])):
+        problems.append(f'version "{manifest["version"]}" 不是语义化版本')
+    known = mode_names()
+    for mode in manifest.get("modes") or []:
+        if mode not in known:
+            problems.append(f'引用了未注册的模式 "{mode}"')
+    return problems