dna-builder-sdk 0.1.0__tar.gz

dna_builder_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 pa001024
+
+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.

dna_builder_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: dna-builder-sdk
+Version: 0.1.0
+Summary: dna-builder 自建后端 + 数据包 + 纯表达式计算的 Python SDK（公开读接口 / 双加载 / 无编辑语义）
+Author: pa001024
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pa001024/dna-builder
+Project-URL: Repository, https://github.com/pa001024/dna-builder
+Project-URL: Issues, https://github.com/pa001024/dna-builder/issues
+Keywords: dna-builder,game-data,sdk,duet-night-abyss
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msgpack>=1.0
+Dynamic: license-file
+
+README.md

dna_builder_sdk-0.1.0/README.md

@@ -0,0 +1,118 @@
+# dna-builder-sdk
+
+dna-builder 后端服务 + 数据包 + 纯表达式计算的 Python SDK。
+
+- **后端**：只覆盖无需登录的公开读接口（评论 / 构筑 / 攻略 / 时间轴 / 榜单 / 脚本 / MOD / DPS / `gameData*`）。写接口、登录态、`admin`、`shop` 私有接口一律不在本包。
+- **数据双加载（同一抽象接口）**：全量 datapack 下载（`versions.json` + `<ver>.zip`），或按模块按需经 `gameData` GraphQL 分页拉取；两者都实现 `TableSource.load_tables()` → `GameDataTables`，上层（`Engine` / `snapshot_from_online` / 示例）只依赖该接口。磁盘持久化并支持运行时热重载。
+- **计算**：纯 BD JSON（CharSettings + charId）进，目标值出。attrs/面板/技能表/伤害乘区
+  全由引擎自算（实体等级化→加成汇总→条件/code 不动点→武器面板→技能结算链），
+  真实 BD 42 个表达式与 bun 真机逐位一致。不含编辑语义（无 AutoBuild、无配装寻优）。
+
+```python
+from dna_builder_sdk import BackendClient, GameDataClient, DataPackStore, ModuleStore
+
+backend = BackendClient()  # 默认 https://api.dna-builder.cn，本地联调传 http://localhost:8887
+gamedata = GameDataClient(backend)
+print(gamedata.modules())
+
+# 数据源抽象接口：两者都实现 load_tables() → GameDataTables（直接给 Engine 用）
+pack = DataPackStore()
+pack.ensure()  # 本地有缓存即激活最新，无缓存则下载远端最新
+print(pack.load_module("char").keys())
+
+# 按需通道：模块列表在声明时确定（缺省 8 张全量表），load_tables() 只拉这些表
+store = ModuleStore(gamedata, modules=["chars", "mods", "weapons", "buffs", "effects"])
+print(store.tables, store.datasets)
+store.preload()  # 可选：一次性预拉取声明过的模块
+store.reload("mod")
+
+# 计算：纯 BD JSON 进，目标值出（表经抽象接口来，测试用最小 fixture）
+from dna_builder_sdk.calc import Engine, GameDataTables, build_state
+
+tables = pack.load_tables()    # 或 store.load_tables()，或 GameDataTables.from_dict({...})
+engine = Engine(build_state(char_id, settings, tables), tables)
+engine.calculate()  # 目标函数值；engine.calculate("[若华纯蓄]DPS") 指定表达式
+
+# 面板与技能：指定等级/MOD/技能等级/溯源
+engine.char_panel()                    # 角色面板（全量角色属性）
+engine.weapon_panel("melee")           # 武器面板（melee/ranged/skill 或技能名）
+engine.skill_levels_final()            # 最终技能等级（含 trio + 溯源加成，钳制 1-12）
+engine.skill_fields("以坚忍之名")      # 技能字段面板数值
+# 技能等级 trio（E/Q/P）与溯源等级（单数；7 即含 1-7 节点效果）
+engine2 = Engine(build_state(cid, settings, tables, skill_levels=[10, 10, 10], traces=7), tables)
+
+# 在线快照：bdid → 线上 JSON → 完整快照（表达式/属性/面板/技能表）
+# 快照与 Engine 走同一条数据通路：传抽象数据源，不再另分支 data_source
+from dna_builder_sdk import snapshot_from_online, snapshot_from_settings
+
+snapshot = snapshot_from_online("Svmqw3LGoY", source=pack)   # 全量通道
+snapshot = snapshot_from_online("Svmqw3LGoY", source=store)  # 或按需通道
+snapshot.calculate()        # 目标函数值
+snapshot.evaluate("角色::攻击!")  # 任意表达式
+snapshot.char_panel()       # 角色面板
+snapshot.summary()          # 一页总览
+# 注：线上实时数据随版本更新，结果跟踪数据版本；回归测试用钉住版本的 fixture。
+
+# 示例：sdk/python/examples/snapshot.py、sdk/python/examples/panels.py
+```
+
+更多接口见各模块 docstring。缓存根目录可用 `DNA_BUILDER_CACHE` 覆盖。
+
+## 发版（GitHub Actions → PyPI，无 token）
+
+本仓用 Trusted Publishing：打 tag 即发版。
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+- 工作流 `.github/workflows/publish.yml`：先跑全量单测，再校验 tag 与
+  `pyproject.toml` 版本一致，最后 `build` + 上传。
+- 只需在 PyPI 上配一次：在账号设置 → Publishing 里加 **pending publisher**
+ （owner `pa001024` / repo `dob-python-sdk` / workflow `publish.yml`），
+  首次上传会自动创建 `dna-builder-sdk` 项目。之后如需轮换，可改用限定项目的作用域。
+
+## 测试报告
+
+运行（仓库根目录，纯本地，无网络）：
+
+```bash
+PYTHONPATH=sdk/python/src python -m unittest discover -s sdk/python/tests
+```
+
+52 tests 全过（含 4 个性能基线）。测试清单：
+
+| 文件 | 覆盖 |
+|---|---|
+| `test_ast_evaluate.py` | 表达式 AST 解析与求值 |
+| `test_data_pack.py` | 数据包 revive/编解码往返 |
+| `test_gamedata_shape.py` | gameData ↔ datapack 形状归一化 |
+| `test_jscode_corpus.py` | 14 段真实 BUFF code 可解析可执行 |
+| `test_shardbuild_parity.py` | 纯 BD JSON：42 表达式 + 全量 attrs/panels 与 bun 真机逐位一致 |
+| `test_online_targets.py` | 6 个线上真实 BD 的变量/target/attrs parity（DOT 分流跳过） |
+| `test_skill_panels.py` | 技能等级 trio + 溯源 + 字段面板 |
+| `test_snapshots.py` | 在线快照装配（fake 后端 + fixture 表） |
+| `test_table_source.py` | 抽象数据源：模块声明、`load_tables()`、快照经 Engine 通路 |
+| `test_datapack_perf.py` | 真实包加载性能基线（`mock/data-pack/1.6.208.6.zip` 钉住版本） |
+| `test_calc_perf.py` | fixture BD 批量计算性能基线（online 六连批 + shard 42 式） |
+
+### 表名映射核验（`calc/gamedata.py` 三处常量，均已对真实包 + 前端 + 服务端验过）
+
+- `MODULE_DEFAULTS`：7 个 datapack 模块（`char/mod/buff/effect/weapon/pet/monster.data`）
+  在真实包内全部存在且皆有 `default` 导出，条数与基线锚点一致。
+- `PET_EXPORTS`：`pets → default`（152 条，对齐前端 `import petData from "./pet.data"`；
+  曾误写 `petData` 导致魔灵表为空，已修正，Go SDK 同步改）、`pet_entries → petEntrys`（73 条）。
+- `DATASET_DEFAULTS`：8 张表 → gameData 数据集 id（`char/mod/buff/effect/weapon/pet/monster` +
+  具名 `pet:petEntrys`），与服务端 `gameDataRegistry` 的模块/数据集 id 逐项一致。
+
+### 性能基线（best 实测，供后人对比；预算只防病态劣化，约实测百倍）
+
+| 基线 | best | 预算 | 锚点 |
+|---|---|---|---|
+| `activate(1.6.208.6)`（manifest + 全包 zip 校验，23MB） | ~166ms（best-of-3） | 60s | manifest.version 吻合 |
+| `load_tables()`（8 表 msgpack 解码 + 索引装配） | ~27ms（best-of-3） | 60s | 8 表条数 `33/586/187/65/71/152/73/393` |
+| online 六 BD 一批（装配 + 目标值 + 全量属性） | ~20ms（best-of-5） | 5s | 目标值 + 全量 attrs 对 `online_expected.json` |
+| shard 一批（42 表达式 + 全量属性） | ~56ms（best-of-3，~750 expr/s） | 10s | 逐式对 `shardBuild1_expr.json` 真机值 |
+
+以上数为开发机实测（Windows / Python 3.14），换机器只对比量级；基线方法（checksum
+锚点先行、best 取 min、每轮等价断言）见技能 `.agents/skills/perf-hotspot-profiling/SKILL.md`。

dna_builder_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dna-builder-sdk"
+version = "0.1.0"
+description = "dna-builder 自建后端 + 数据包 + 纯表达式计算的 Python SDK（公开读接口 / 双加载 / 无编辑语义）"
+readme = { text = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE*"]
+authors = [{ name = "pa001024" }]
+keywords = ["dna-builder", "game-data", "sdk", "duet-night-abyss"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["msgpack>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/pa001024/dna-builder"
+Repository = "https://github.com/pa001024/dna-builder"
+Issues = "https://github.com/pa001024/dna-builder/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"

dna_builder_sdk-0.1.0/setup.cfg

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

dna_builder_sdk-0.1.0/src/dna_builder_sdk/__init__.py

@@ -0,0 +1,27 @@
+"""dna-builder Python SDK：自建后端公开读接口 + 数据双加载 + 纯表达式计算。"""
+
+from .backend import BackendClient
+from .calc.gamedata import TableSource, resolve_tables
+from .data_pack import DataPackStore, revive_packed_value
+from .errors import DobApiError, DobGraphQLError, DobHttpError
+from .game_data import GameDataClient
+from .module_store import ModuleStore
+from .snapshots import BuildSnapshot, snapshot_from_online, snapshot_from_settings
+
+__all__ = [
+    "BackendClient",
+    "GameDataClient",
+    "DataPackStore",
+    "ModuleStore",
+    "TableSource",
+    "BuildSnapshot",
+    "resolve_tables",
+    "snapshot_from_online",
+    "snapshot_from_settings",
+    "revive_packed_value",
+    "DobApiError",
+    "DobHttpError",
+    "DobGraphQLError",
+]
+
+__version__ = "0.1.0"

dna_builder_sdk-0.1.0/src/dna_builder_sdk/backend.py

@@ -0,0 +1,202 @@
+"""自建后端（Elysia）传输层 + 公开读接口。
+
+只覆盖无需登录的 Query：评论 / 构筑 / 攻略 / 时间轴 / 榜单 / 脚本 /
+MOD / DPS / gameData*。Mutation、admin、shop 私有、my* 一律不实现。
+标准库 urllib 实现零额外 HTTP 依赖，302 默认跟随。
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .errors import DobGraphQLError, DobHttpError
+
+_DEFAULT_TIMEOUT = 30
+
+
+def _post_json(url: str, payload: dict, timeout: float) -> tuple[int, dict | list, str]:
+    """POST JSON 并返回 (status, body, final_url)，302 由 opener 自动跟随。"""
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"content-type": "application/json", "accept": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, json.loads(resp.read().decode("utf-8")), resp.geturl()
+    except urllib.error.HTTPError as exc:
+        try:
+            body = json.loads(exc.read().decode("utf-8"))
+        except Exception:
+            body = {"message": str(exc)}
+        raise DobHttpError(f"HTTP {exc.code}: {url}", status=exc.code, payload=body) from exc
+    except urllib.error.URLError as exc:
+        raise DobHttpError(f"连接失败: {url} ({exc.reason})", status=0) from exc
+
+
+def _get_json(url: str, timeout: float):
+    req = urllib.request.Request(url, headers={"accept": "application/json"}, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        raise DobHttpError(f"HTTP {exc.code}: {url}", status=exc.code) from exc
+    except urllib.error.URLError as exc:
+        raise DobHttpError(f"连接失败: {url} ({exc.reason})", status=0) from exc
+
+
+class BackendClient:
+    """自建后端客户端，默认线上端点；本地联调传 http://localhost:8887。"""
+
+    def __init__(self, base_url: str = "https://api.dna-builder.cn", timeout: float = _DEFAULT_TIMEOUT):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    @property
+    def graphql_url(self) -> str:
+        return f"{self.base_url}/graphql"
+
+    def graphql(self, query: str, variables: dict | None = None) -> dict:
+        """裸 GraphQL 调用，errors 非空时抛 DobGraphQLError。"""
+        _, body, _ = _post_json(self.graphql_url, {"query": query, "variables": variables or {}}, self.timeout)
+        if not isinstance(body, dict):
+            raise DobGraphQLError(f"网关返回非对象: {body!r}", errors=[body])
+        if body.get("errors"):
+            first = body["errors"][0]
+            msg = first.get("message", "graphql error") if isinstance(first, dict) else str(first)
+            raise DobGraphQLError(msg, errors=body["errors"])
+        return body.get("data") or {}
+
+    # ---- 评论（读） ----
+    def comments(self, target_id: str, limit: int = 50, offset: int = 0) -> list:
+        data = self.graphql(
+            "query($t:String!,$l:Int,$o:Int){comments(targetId:$t,limit:$l,offset:$o){id targetId content createdAt user{id name}}}",
+            {"t": target_id, "l": limit, "o": offset},
+        )
+        return data.get("comments") or []
+
+    def comments_count(self, target_id: str) -> int:
+        data = self.graphql("query($t:String!){commentsCount(targetId:$t)}", {"t": target_id})
+        return int(data.get("commentsCount") or 0)
+
+    # ---- 构筑（读） ----
+    def builds(self, search=None, char_id=None, user_id=None, limit=20, offset=0, sort_by="latest") -> list:
+        data = self.graphql(
+            "query($s:String,$c:Int,$u:String,$l:Int,$o:Int,$sb:String)"
+            "{builds(search:$s,charId:$c,userId:$u,limit:$l,offset:$o,sortBy:$sb)"
+            "{id title desc charId userId views likes isRecommended isPinned createdAt updateAt targetValue charSettings}}",
+            {"s": search, "c": char_id, "u": user_id, "l": limit, "o": offset, "sb": sort_by},
+        )
+        return data.get("builds") or []
+
+    def builds_count(self, search=None, char_id=None) -> int:
+        data = self.graphql(
+            "query($s:String,$c:Int){buildsCount(search:$s,charId:$c)}", {"s": search, "c": char_id}
+        )
+        return int(data.get("buildsCount") or 0)
+
+    def build(self, build_id: str) -> dict | None:
+        data = self.graphql(
+            "query($id:String!){build(id:$id){id title desc charId charSettings userId views likes createdAt updateAt targetValue}}",
+            {"id": build_id},
+        )
+        return data.get("build")
+
+    def recommended_builds(self, limit=10) -> list:
+        return (self.graphql("query($l:Int){recommendedBuilds(limit:$l){id title charId likes views}}", {"l": limit}).get("recommendedBuilds") or [])
+
+    def trending_builds(self, limit=10) -> list:
+        return (self.graphql("query($l:Int){trendingBuilds(limit:$l){id title charId likes views}}", {"l": limit}).get("trendingBuilds") or [])
+
+    # ---- 攻略（读） ----
+    def guides(self, search=None, type=None, char_id=None, user_id=None, limit=20, offset=0) -> list:
+        data = self.graphql(
+            "query($s:String,$t:String,$c:Int,$u:String,$l:Int,$o:Int)"
+            "{guides(search:$s,type:$t,charId:$c,userId:$u,limit:$l,offset:$o){id title type charId views likes createdAt updateAt}}",
+            {"s": search, "t": type, "c": char_id, "u": user_id, "l": limit, "o": offset},
+        )
+        return data.get("guides") or []
+
+    def guide(self, guide_id: str) -> dict | None:
+        data = self.graphql(
+            "query($id:String!){guide(id:$id){id title type content images charId buildId views likes createdAt updateAt}}",
+            {"id": guide_id},
+        )
+        return data.get("guide")
+
+    # ---- 时间轴（读） ----
+    def timelines(self, search=None, char_id=None, user_id=None, limit=20, offset=0, sort_by="recent") -> list:
+        data = self.graphql(
+            "query($s:String,$c:Int,$u:String,$l:Int,$o:Int,$sb:String)"
+            "{timelines(search:$s,charId:$c,userId:$u,limit:$l,offset:$o,sortBy:$sb){id title charId views likes createdAt updateAt}}",
+            {"s": search, "c": char_id, "u": user_id, "l": limit, "o": offset, "sb": sort_by},
+        )
+        return data.get("timelines") or []
+
+    def timeline(self, timeline_id: str) -> dict | None:
+        data = self.graphql(
+            "query($id:String!){timeline(id:$id){id title charId views likes createdAt updateAt}}",
+            {"id": timeline_id},
+        )
+        return data.get("timeline")
+
+    # ---- 榜单（读） ----
+    def ranking_lists(self) -> list:
+        return (self.graphql("{rankingLists{id name desc createdAt updateAt}}").get("rankingLists") or [])
+
+    def ranking_list(self, list_id: str) -> dict | None:
+        data = self.graphql(
+            "query($id:String!){rankingList(id:$id){id name desc items{id charId buildId sortOrder}}}",
+            {"id": list_id},
+        )
+        return data.get("rankingList")
+
+    def ranking_list_items(self, ranking_list_id: str) -> list:
+        data = self.graphql(
+            "query($id:String!){rankingListItems(rankingListId:$id){id charId buildId sortOrder}}",
+            {"id": ranking_list_id},
+        )
+        return data.get("rankingListItems") or []
+
+    # ---- 脚本 / MOD / DPS（读） ----
+    def scripts(self, search=None, category=None, user_id=None, limit=20, offset=0) -> list:
+        data = self.graphql(
+            "query($s:String,$c:String,$u:String,$l:Int,$o:Int)"
+            "{scripts(search:$s,category:$c,userId:$u,limit:$l,offset:$o){id title category createdAt updateAt}}",
+            {"s": search, "c": category, "u": user_id, "l": limit, "o": offset},
+        )
+        return data.get("scripts") or []
+
+    def script(self, script_id: str, preview: bool = False) -> dict | None:
+        data = self.graphql(
+            "query($id:String!,$p:Boolean){script(id:$id,preview:$p){id title category content}}",
+            {"id": script_id, "p": preview},
+        )
+        return data.get("script")
+
+    def game_mods(self, search=None, category=None, entity=None, limit=20, offset=0, sort_by=None) -> list:
+        data = self.graphql(
+            "query($s:String,$c:String,$e:String,$l:Int,$o:Int,$sb:String)"
+            "{gameMods(search:$s,category:$c,entity:$e,limit:$l,offset:$o,sortBy:$sb){id title category entity status createdAt updateAt}}",
+            {"s": search, "c": category, "e": entity, "l": limit, "o": offset, "sb": sort_by},
+        )
+        return data.get("gameMods") or []
+
+    def game_mod(self, mod_id: str) -> dict | None:
+        data = self.graphql(
+            "query($id:String!){gameMod(id:$id){id title category entity status}}", {"id": mod_id}
+        )
+        return data.get("gameMod")
+
+    def dps_list(self, char_id=None, build_id=None, timeline_id=None, limit=20, offset=0, sort_by="dpsValue") -> list:
+        data = self.graphql(
+            "query($c:Int,$b:String,$t:String,$l:Int,$o:Int,$sb:String)"
+            "{dpsList(charId:$c,buildId:$b,timelineId:$t,limit:$l,offset:$o,sortBy:$sb){id charId buildId dpsValue createdAt}}",
+            {"c": char_id, "b": build_id, "t": timeline_id, "l": limit, "o": offset, "sb": sort_by},
+        )
+        return data.get("dpsList") or []

dna_builder_sdk-0.1.0/src/dna_builder_sdk/calc/__init__.py

@@ -0,0 +1,13 @@
+"""calc 包：BD 装配 + 聚合引擎 + 表达式/伤害结算（无编辑语义）。"""
+
+from .ast import AstError, parse_ast, tokenize_ast
+from .build import build_state, parse_trace_levels
+from .damage import DamageContext
+from .engine import Engine
+from .evaluate import evaluate
+from .gamedata import GameDataTables, TableSource, resolve_tables
+
+__all__ = [
+    "AstError", "DamageContext", "Engine", "GameDataTables", "TableSource",
+    "build_state", "parse_trace_levels", "parse_ast", "tokenize_ast", "evaluate", "resolve_tables",
+]