dse-core 0.1.0__tar.gz

dse_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 全哥 (siwpan)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dse_core-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: dse-core
+Version: 0.1.0
+Summary: 字典场景引擎（Dictionary Scene Engine）—— 场景即字典，能力即插件
+Author: 全哥 (siwpan)
+License: MIT
+Project-URL: Homepage, https://gitee.com/siwpan/cordis-py
+Project-URL: Repository, https://gitee.com/siwpan/cordis-py
+Project-URL: Issues, https://gitee.com/siwpan/cordis-py/issues
+Keywords: text-adventure,interactive-fiction,game-engine,plugin-architecture,narrative-engine,dialogue-graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# dse-core · 字典场景引擎（Python 版）
+
+> Dictionary Scene Engine —— 场景即字典，能力即插件。
+> 本仓库是引擎的 **Python 原生实现**（cordis-py），Node/Cordis 版见姊妹仓库
+> [dse-core](https://gitee.com/siwpan/dse-core)。立项计划书见 [PLAN.md](PLAN.md)。
+
+## 30 秒上手
+
+```bash
+pip install -e .          # 开发安装（或 pip install dse-core）
+dse play                  # 玩自带示例内容包（战斗线最小可玩版）
+dse play --input "1,1,a,a,a"   # 脚本模式：无交互跑完整条线路（CI 友好）
+dse scenes                # 列出场景
+dse check                 # 校验内容（悬空跳转等），有问题退出码 1
+```
+
+自带示例工程随包发布（`src/dse_core/example/`）：在含 `dse.yml` 的目录里
+运行 `dse play` 玩你自己的工程，否则玩包内示例。
+
+## 内容包 = 数据，不是代码
+
+与 Node 版最大的差异：内容包是 **YAML 数据文件**，不是可执行模块。
+条件表达式经 **AST 白名单求值**（仅比较/布尔/算术/下标，禁调用、禁下划线属性）——
+不需要 import 任何用户代码，也没有 `new Function`。
+
+```yaml
+# content/starter.yml（节选）
+pack:
+  id: starter
+  name: 启程
+  entry: start
+scenes:
+  start:
+    title: 村口 · 启程
+    text: '天没亮透……三条路摆在你面前。'
+    choices:
+      - { text: '往北进山', do: { 'flags.starter.mountain': true }, goto: forest }
+  forest:
+    text: '……一只独眼狼从阴影里站起来。'
+    choices:
+      - { text: '拔剑', goto: wolf-fight }
+  wolf-fight:
+    mode: battle                      # 非 normal 模式由能力插件接管
+    battle: { enemy: wolf, onWin: forest-win, onLose: forest-lose, onFlee: start }
+```
+
+## 架构
+
+```
+dse_core/
+├── modes.py       # 模式注册表（scene.mode 唯一真源）
+├── graph.py       # 场景图静态分析（可达性/悬空/结局/最短路径，纯函数）
+├── manifest.py    # 内容包元数据（规范化/校验）
+├── loader.py      # 工程加载（dse.yml + YAML 内容包合并）
+├── schema.py      # JSON Schema 校验（schema/scene.schema.json）
+├── safety.py      # 条件表达式 AST 白名单求值
+├── runtime.py     # 插件运行时（Service/Context/依赖拓扑/事件）—— Cordis 的 Python 原生替代
+├── sdk.py         # 编程式门面（create_engine / play / inspect_project）
+├── cli.py         # 命令行 dse：play / scenes / info / check
+└── plugins/       # 内核层 scenes/state/console_io/engine + 参考能力插件 combat
+```
+
+插件用声明式依赖组装，引擎零改动即可扩展：
+
+```python
+from dse_core.runtime import Service
+
+class MyPlugin(Service):
+    name = "my-plugin"
+    inject = ("state", "io")          # 等价于 Cordis 的 static inject
+    def setup(self):
+        self.ctx.on("scene/enter", lambda scene_id, scene: ...)
+```
+
+## 与 Node 版的关系
+
+- Node 版持续维护；本仓库是**移植版**，内容格式不互通（YAML ↔ ESM）。
+- 移植路线图：**P1 可发布最小引擎（本阶段）→ P2 系统层（save/achievements/i18n）+ 完整 CLI → P3 能力层（trade/dialogue/diary）→ P4 表现层（sound/hot-reload）+ 内容迁移工具**。详见 [PLAN.md](PLAN.md)。
+
+## 安全模型
+
+- 内容包是数据；表达式求值禁调用与下划线属性访问。
+- `dse.yml` 与内容包路径均限制在工程目录内（路径白名单）。
+
+## License
+
+MIT · Copyright (c) 2026 全哥 (siwpan)

dse_core-0.1.0/README.md

@@ -0,0 +1,87 @@
+# dse-core · 字典场景引擎（Python 版）
+
+> Dictionary Scene Engine —— 场景即字典，能力即插件。
+> 本仓库是引擎的 **Python 原生实现**（cordis-py），Node/Cordis 版见姊妹仓库
+> [dse-core](https://gitee.com/siwpan/dse-core)。立项计划书见 [PLAN.md](PLAN.md)。
+
+## 30 秒上手
+
+```bash
+pip install -e .          # 开发安装（或 pip install dse-core）
+dse play                  # 玩自带示例内容包（战斗线最小可玩版）
+dse play --input "1,1,a,a,a"   # 脚本模式：无交互跑完整条线路（CI 友好）
+dse scenes                # 列出场景
+dse check                 # 校验内容（悬空跳转等），有问题退出码 1
+```
+
+自带示例工程随包发布（`src/dse_core/example/`）：在含 `dse.yml` 的目录里
+运行 `dse play` 玩你自己的工程，否则玩包内示例。
+
+## 内容包 = 数据，不是代码
+
+与 Node 版最大的差异：内容包是 **YAML 数据文件**，不是可执行模块。
+条件表达式经 **AST 白名单求值**（仅比较/布尔/算术/下标，禁调用、禁下划线属性）——
+不需要 import 任何用户代码，也没有 `new Function`。
+
+```yaml
+# content/starter.yml（节选）
+pack:
+  id: starter
+  name: 启程
+  entry: start
+scenes:
+  start:
+    title: 村口 · 启程
+    text: '天没亮透……三条路摆在你面前。'
+    choices:
+      - { text: '往北进山', do: { 'flags.starter.mountain': true }, goto: forest }
+  forest:
+    text: '……一只独眼狼从阴影里站起来。'
+    choices:
+      - { text: '拔剑', goto: wolf-fight }
+  wolf-fight:
+    mode: battle                      # 非 normal 模式由能力插件接管
+    battle: { enemy: wolf, onWin: forest-win, onLose: forest-lose, onFlee: start }
+```
+
+## 架构
+
+```
+dse_core/
+├── modes.py       # 模式注册表（scene.mode 唯一真源）
+├── graph.py       # 场景图静态分析（可达性/悬空/结局/最短路径，纯函数）
+├── manifest.py    # 内容包元数据（规范化/校验）
+├── loader.py      # 工程加载（dse.yml + YAML 内容包合并）
+├── schema.py      # JSON Schema 校验（schema/scene.schema.json）
+├── safety.py      # 条件表达式 AST 白名单求值
+├── runtime.py     # 插件运行时（Service/Context/依赖拓扑/事件）—— Cordis 的 Python 原生替代
+├── sdk.py         # 编程式门面（create_engine / play / inspect_project）
+├── cli.py         # 命令行 dse：play / scenes / info / check
+└── plugins/       # 内核层 scenes/state/console_io/engine + 参考能力插件 combat
+```
+
+插件用声明式依赖组装，引擎零改动即可扩展：
+
+```python
+from dse_core.runtime import Service
+
+class MyPlugin(Service):
+    name = "my-plugin"
+    inject = ("state", "io")          # 等价于 Cordis 的 static inject
+    def setup(self):
+        self.ctx.on("scene/enter", lambda scene_id, scene: ...)
+```
+
+## 与 Node 版的关系
+
+- Node 版持续维护；本仓库是**移植版**，内容格式不互通（YAML ↔ ESM）。
+- 移植路线图：**P1 可发布最小引擎（本阶段）→ P2 系统层（save/achievements/i18n）+ 完整 CLI → P3 能力层（trade/dialogue/diary）→ P4 表现层（sound/hot-reload）+ 内容迁移工具**。详见 [PLAN.md](PLAN.md)。
+
+## 安全模型
+
+- 内容包是数据；表达式求值禁调用与下划线属性访问。
+- `dse.yml` 与内容包路径均限制在工程目录内（路径白名单）。
+
+## License
+
+MIT · Copyright (c) 2026 全哥 (siwpan)

dse_core-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dse-core"
+version = "0.1.0"
+description = "字典场景引擎（Dictionary Scene Engine）—— 场景即字典，能力即插件"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "全哥 (siwpan)" }]
+keywords = [
+    "text-adventure",
+    "interactive-fiction",
+    "game-engine",
+    "plugin-architecture",
+    "narrative-engine",
+    "dialogue-graph",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    "PyYAML>=6.0",
+    "jsonschema>=4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://gitee.com/siwpan/cordis-py"
+Repository = "https://gitee.com/siwpan/cordis-py"
+Issues = "https://gitee.com/siwpan/cordis-py/issues"
+
+[project.scripts]
+dse = "dse_core.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dse_core = ["schema/*.json", "example/dse.yml", "example/content/*.yml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dse_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dse_core-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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 } }