python-library-ff14-the-hunt 0.0.0__tar.gz

python_library_ff14_the_hunt-0.0.0/.cursor/skills/ff14_the_hunt-package-changelog/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: ff14-the-hunt-package-changelog
+description: ff14_the_hunt 包：要求与决议；最新在上。
+---
+
+# ff14_the_hunt · Changelog
+
+（规则见 `~/.cursor/skills/agent-project-changelog/SKILL.md`。）
+
+## 2026-06-04
+
+- **决议**：包目录由 **`ff14_world_boss`** 重命名为 **`ff14_the_hunt`**；PyPI 名 **`python-library-ff14-the-hunt`**；包级 skill 同步为 **`ff14_the_hunt-package-*`**。不考虑旧名兼容。
+- **决议**：在 monorepo 初始化空包（初名 **ff14_world_boss**），并建立包级三件套。

python_library_ff14_the_hunt-0.0.0/.cursor/skills/ff14_the_hunt-package-design/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ff14-the-hunt-package-design
+description: >-
+  ff14_the_hunt 包：当前有效的设计意图；变更见 ff14_the_hunt-package-changelog。
+---
+
+# ff14_the_hunt · 设计笔记
+
+> 变更见 `.cursor/skills/ff14_the_hunt-package-changelog/SKILL.md`；矛盾以 changelog 最新为准。
+
+## 设计意图
+
+- **FF14 狩猎（The Hunt）**：本包用于最终幻想 XIV 狩猎相关信息的获取与处理（具体数据源与输出形态待定）。
+
+## 硬性要求
+
+- 包目录名 **`ff14_the_hunt`**（snake_case）；PyPI 名 **`python-library-ff14-the-hunt`**。
+- 中文禁用词见 `~/.cursor/skills/forbidden-doc-comment-vocabulary/SKILL.md`。
+
+## 备忘与待定
+
+- 数据源、提醒方式、对外 API 形态尚未确定。

python_library_ff14_the_hunt-0.0.0/.cursor/skills/ff14_the_hunt-package-preload/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: ff14-the-hunt-package-preload
+description: ff14_the_hunt 包：会话预加载；改本包源码前 Read。
+---
+
+# ff14_the_hunt · 会话预加载
+
+## 初始化加载（Session preload）
+
+在 **`packages/ff14_the_hunt/`** 下改源码、测试或 `pyproject.toml` 时，按序 **Read**：
+
+1. `~/.cursor/skills/project-skill-manifest-policy/SKILL.md`
+2. `~/.cursor/skills/forbidden-doc-comment-vocabulary/SKILL.md`
+3. `~/.cursor/skills/markdown-authoring-zh/SKILL.md`
+4. `~/.cursor/skills/python-project-ai/SKILL.md`
+5. `~/.cursor/skills/python-doc-comments/SKILL.md`
+6. `~/.cursor/skills/agent-codegen-self-review/SKILL.md`
+7. `.cursor/skills/ff14_the_hunt-package-design/SKILL.md`
+8. `.cursor/skills/ff14_the_hunt-package-changelog/SKILL.md`
+
+整库约定见仓库根 `.cursor/skills/python-library-session-manifest/SKILL.md`。
+
+## 用过的 skill（追加记录）
+
+（初始为空。）

python_library_ff14_the_hunt-0.0.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# example 抓取产物
+example/output/

python_library_ff14_the_hunt-0.0.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: python-library-ff14-the-hunt
+Version: 0.0.0
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

python_library_ff14_the_hunt-0.0.0/README.md

@@ -0,0 +1,50 @@
+# ff14_the_hunt
+
+从 [Bear Tracker](https://tracker.beartoolkit.com/timer) 拉取狩猎计时，解析触发窗/条件窗，并判断「刚刷新」。
+
+## 用法
+
+```python
+from ff14_the_hunt import FF14TheHunt, HuntQueryFilter, HuntRankKind
+
+hunt = FF14TheHunt()
+marks = hunt.query_marks(
+    HuntQueryFilter(
+        data_centers=["猫小胖"],
+        worlds=["静语庄园"],
+        rank_kinds=[HuntRankKind.S, HuntRankKind.A],
+        patches=["DT"],
+    )
+)
+recent = hunt.recently_spawned(
+    HuntQueryFilter(
+        data_centers=["猫小胖"],
+        worlds=["静语庄园"],
+        rank_kinds=[HuntRankKind.S],
+    )
+)
+```
+
+## 示例
+
+```bat
+example.bat
+```
+
+或 `python -m example`。输出写入 `example/output/`（已列入 `.gitignore`）。
+
+## API 说明
+
+| 站点接口 | 用途 |
+| --- | --- |
+| `POST /api/syncSession` | 狩猎库、刷点坐标、数据中心/世界列表 |
+| `POST /api/lastDeathTimers` | 计时行；`RankType` 为 `aRank` / `sRank` / `fate` |
+| `POST /api/querySpawnPoints` | 各刷点是否已激活（需 `LastDeath`） |
+
+`QueryDeathTimers` 为世界名列表（由所选数据中心展开）。
+
+资料片筛选使用资源库中的 `Patch` 字段（7.0 金曦之遗辉 → `DT`）。
+
+触发时间窗算法与站点前端主计时列一致；带 `fateLastSeen` / `fateLastDeath` 的 7.0 S 链使用 FATE 条件计时。部分老式 S（如 Laideronnette）的天气条件窗尚未移植。
+
+「刚刷新」：触发窗开启后默认 15 分钟内，或 `lastMarkTime` 在默认 15 分钟内。

python_library_ff14_the_hunt-0.0.0/example/__main__.py

@@ -0,0 +1,69 @@
+"""示例：中国服务器 · 猫小胖 · 静语庄园 · 7.0（DT）· S 狩猎。
+
+资料片「金曦之遗辉」在 Bear Tracker 内对应 ``Patch=DT``。
+示例目标：DT 地图乌克帕夏的 Arch Aethereater Urqopacha（国服常称乌克帕夏 S 链）。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ff14_the_hunt import FF14TheHunt, HuntQueryFilter, HuntRankKind
+
+DC_MOOGLE = "\u732b\u5c0f\u80d6"
+WORLD_MANOR = "\u9759\u8bed\u5e84\u56ed"
+PATCH_DAWNTRAIL = "DT"
+EXAMPLE_HUNT = "Arch Aethereater Urqopacha"
+
+
+def main() -> None:
+    hunt = FF14TheHunt()
+    print("中国区数据中心:", hunt.list_data_centers(region="CN"))
+
+    query = HuntQueryFilter(
+        data_centers=[DC_MOOGLE],
+        worlds=[WORLD_MANOR],
+        rank_kinds=[HuntRankKind.S],
+        patches=[PATCH_DAWNTRAIL],
+        hunt_keys=[EXAMPLE_HUNT],
+    )
+
+    marks = hunt.query_marks(query, include_spawn_states=True)
+    recent = hunt.recently_spawned(query)
+
+    out_dir = Path(__file__).resolve().parent / "output"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    payload = {
+        "query": query.model_dump(),
+        "marks": [m.model_dump() for m in marks],
+        "recently_spawned": [m.model_dump() for m in recent],
+    }
+    out_path = out_dir / "bear_moogle_manor_dt_s.json"
+    out_path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+    print(f"写入 {out_path}")
+    for mark in marks:
+        print("---")
+        print(mark.hunt_name, mark.world_name, mark.region, mark.patch)
+        if mark.trigger_timer:
+            print("  触发:", mark.trigger_timer.summary)
+        if mark.condition_timer:
+            print("  条件:", mark.condition_timer.summary)
+        if mark.spawn_points:
+            pt = mark.spawn_points[0]
+            print(
+                f"  区域坐标(地图格点): {pt.point_key} "
+                f"grid=({pt.grid_x}, {pt.grid_y}) norm=({pt.x:.3f}, {pt.y:.3f})"
+            )
+        print("  刚刷新:", mark.recently_spawned)
+
+    print(f"同条件下刚刷新 {len(recent)} 条")
+
+
+if __name__ == "__main__":
+    main()

python_library_ff14_the_hunt-0.0.0/example.bat

@@ -0,0 +1,10 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    call update.bat
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e . -q
+python -m example %*

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/__init__.py

@@ -0,0 +1,19 @@
+from ff14_the_hunt.ff14_the_hunt import FF14TheHunt
+from ff14_the_hunt.models import (
+    HuntMarkRecord,
+    HuntQueryFilter,
+    HuntRankKind,
+    MapCoordinate,
+    SpawnWindowPhase,
+    TimerDisplay,
+)
+
+__all__ = [
+    "FF14TheHunt",
+    "HuntMarkRecord",
+    "HuntQueryFilter",
+    "HuntRankKind",
+    "MapCoordinate",
+    "SpawnWindowPhase",
+    "TimerDisplay",
+]

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/bear_tracker/__init__.py

@@ -0,0 +1,3 @@
+from ff14_the_hunt.bear_tracker.client import BearTrackerClient
+
+__all__ = ["BearTrackerClient"]

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/bear_tracker/client.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+DEFAULT_BASE_URL = "https://tracker.beartoolkit.com/api"
+
+
+class BearTrackerClient:
+    """Bear Tracker 站点同源 API 客户端（``/api/*``）。"""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_seconds: float = 120.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout_seconds = timeout_seconds
+
+    def sync_session(self) -> dict[str, Any]:
+        """拉取会话与 ``resources``（含 DatabaseHunt、SpawnPoint、DataCenters）。"""
+        return self._post("/syncSession", {})
+
+    def last_death_timers(
+        self,
+        *,
+        world_names: list[str],
+        rank_type: str,
+    ) -> list[dict[str, Any]]:
+        """按世界列表查询死亡/计时记录。
+
+        Args:
+            world_names: 世界名列表（由数据中心展开或直接指定）。
+            rank_type: ``aRank``、``sRank`` 或 ``fate``。
+        """
+        payload = {
+            "QueryDeathTimers": world_names,
+            "RankType": rank_type,
+        }
+        data = self._post("/lastDeathTimers", payload)
+        timers = data.get("timers", [])
+        if isinstance(timers, dict):
+            return list(timers.values())
+        if isinstance(timers, list):
+            return timers
+        return []
+
+    def hunt_info(self, *, hunt_name: str, world_name: str) -> dict[str, Any]:
+        return self._post(
+            "/huntInfo",
+            {"HuntName": hunt_name, "WorldName": world_name},
+        )
+
+    def query_spawn_points(
+        self,
+        *,
+        hunt_name: str,
+        world_name: str,
+        last_death: float | None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "WorldName": world_name,
+            "HuntName": hunt_name,
+            "QuerySpawnPoint": "Query",
+        }
+        if last_death is not None:
+            body["LastDeath"] = last_death
+        result = self._post("/querySpawnPoints", body)
+        if isinstance(result, dict):
+            return result.get("data", result)
+        return {}
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        encoded = json.dumps(body).encode("utf-8")
+        request = urllib.request.Request(
+            url,
+            data=encoded,
+            headers={
+                "User-Agent": "python-library-ff14-the-hunt",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Origin": "https://tracker.beartoolkit.com",
+                "Referer": "https://tracker.beartoolkit.com/timer",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(
+                request,
+                timeout=self._timeout_seconds,
+            ) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeError(
+                f"Bear Tracker API {path} failed: HTTP {exc.code}: {detail}"
+            ) from exc
+        parsed = json.loads(raw.decode("utf-8"))
+        if not isinstance(parsed, dict):
+            raise RuntimeError(f"unexpected response type from {path}")
+        return parsed

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/bear_tracker/enrich.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from ff14_the_hunt.models import HuntMarkRecord, HuntQueryFilter, TimerDisplay
+
+from ff14_the_hunt.bear_tracker.fate_timer import compute_fate_condition_timer
+from ff14_the_hunt.bear_tracker.resources import BearResources
+from ff14_the_hunt.bear_tracker.spawn_points import list_map_coordinates
+from ff14_the_hunt.bear_tracker.spawn_window import (
+    compute_trigger_timer,
+    is_recently_in_window,
+)
+
+
+def _passes_filter(
+    *,
+    hunt_key: str,
+    meta: dict[str, Any],
+    world_name: str,
+    query: HuntQueryFilter,
+) -> bool:
+    if query.hunt_keys and hunt_key not in query.hunt_keys:
+        return False
+    patch = str(meta.get("Patch", ""))
+    if query.patches and patch not in query.patches:
+        return False
+    region = meta.get("Region", "")
+    if query.regions:
+        region_text = region if isinstance(region, str) else " ".join(region)
+        if not any(item in region_text for item in query.regions):
+            return False
+    if query.worlds and world_name not in query.worlds:
+        return False
+    return True
+
+
+def build_hunt_record(
+    *,
+    timer_row: dict[str, Any],
+    resources: BearResources,
+    spawn_states: dict[str, Any] | None,
+    query: HuntQueryFilter,
+    now: float | None = None,
+    recent_grace_seconds: float = 900.0,
+) -> HuntMarkRecord | None:
+    hunt_key = str(timer_row.get("huntKey") or timer_row.get("huntName") or "")
+    world_name = str(timer_row.get("worldName") or "")
+    if not hunt_key or not world_name:
+        return None
+
+    meta = resources.hunt_meta(hunt_key)
+    if not _passes_filter(
+        hunt_key=hunt_key,
+        meta=meta,
+        world_name=world_name,
+        query=query,
+    ):
+        return None
+
+    is_maint = bool(timer_row.get("isMaint"))
+    timer_pair = meta.get("MaintTimer") if is_maint else meta.get("RespawnTimer")
+    last_death = timer_row.get("lastDeathTime")
+    last_mark = timer_row.get("lastMarkTime")
+    missing = float(timer_row.get("missingCounter") or 0.0)
+
+    trigger: TimerDisplay | None = None
+    if isinstance(timer_pair, (list, tuple)) and len(timer_pair) >= 2 and last_death:
+        trigger = compute_trigger_timer(
+            respawn_hours=(float(timer_pair[0]), float(timer_pair[1])),
+            last_death_time=float(last_death),
+            last_mark_time=float(last_mark) if last_mark else None,
+            missing_counter=missing,
+            now=now,
+        )
+
+    condition = compute_fate_condition_timer(
+        last_death_time=float(last_death or 0.0),
+        fate_last_seen=timer_row.get("fateLastSeen"),
+        fate_last_death=timer_row.get("fateLastDeath"),
+        now=now,
+    )
+
+    map_key = resources.spawn_map_key(hunt_key, meta)
+    spawn_entry = resources.spawn_point.get(map_key) if map_key else None
+    points = list_map_coordinates(spawn_entry, api_states=spawn_states)
+
+    recently = is_recently_in_window(trigger, grace_seconds=recent_grace_seconds)
+    if last_mark and now is not None:
+        if now - float(last_mark) <= recent_grace_seconds:
+            recently = True
+    elif last_mark:
+        if time.time() - float(last_mark) <= recent_grace_seconds:
+            recently = True
+
+    region = meta.get("Region", "")
+    return HuntMarkRecord(
+        hunt_key=hunt_key,
+        hunt_name=str(timer_row.get("huntName") or hunt_key),
+        world_name=world_name,
+        region=region,
+        patch=str(meta.get("Patch", "")),
+        rank=meta.get("Rank"),
+        last_death_time=float(last_death) if last_death else None,
+        last_mark_time=float(last_mark) if last_mark else None,
+        missing_counter=missing,
+        is_maintenance=is_maint,
+        fate_last_seen=timer_row.get("fateLastSeen"),
+        fate_last_death=timer_row.get("fateLastDeath"),
+        trigger_timer=trigger,
+        condition_timer=condition,
+        spawn_points=points,
+        recently_spawned=recently,
+        raw_timer=dict(timer_row),
+    )

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/bear_tracker/fate_timer.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import time
+
+from ff14_the_hunt.models import SpawnWindowPhase, TimerDisplay
+
+from ff14_the_hunt.bear_tracker.spawn_window import _format_duration
+
+
+def compute_fate_condition_timer(
+    *,
+    last_death_time: float,
+    fate_last_seen: float | None,
+    fate_last_death: float | None,
+    now: float | None = None,
+) -> TimerDisplay | None:
+    """7.0 部分 S 猎（如 Arch Aethereater）使用的 FATE 链条件计时（组件 ``lo`` 前半）。"""
+    if fate_last_seen is None or fate_last_death is None:
+        return None
+    if now is None:
+        now = time.time()
+    now_ms = now * 1000.0
+    seen_ms = fate_last_seen * 1000.0
+    death_ms = fate_last_death * 1000.0
+
+    if death_ms > seen_ms:
+        delta = now_ms - death_ms
+        return TimerDisplay(
+            label="condition",
+            phase=SpawnWindowPhase.CLOSED,
+            elapsed_seconds=delta / 1000.0,
+            summary=f"FATE 已结束 {_format_duration(delta / 1000.0)}",
+        )
+
+    delta = now_ms - seen_ms
+    return TimerDisplay(
+        label="condition",
+        phase=SpawnWindowPhase.OPEN,
+        elapsed_seconds=delta / 1000.0,
+        summary=f"FATE 进行中 {_format_duration(delta / 1000.0)}",
+    )

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/bear_tracker/resources.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class BearResources:
+    """``syncSession`` 返回的 resources 只读视图。"""
+
+    def __init__(self, resources: dict[str, Any]) -> None:
+        self._resources = resources
+
+    @property
+    def database_hunt(self) -> dict[str, Any]:
+        return self._resources.get("DatabaseHunt", {})
+
+    @property
+    def spawn_point(self) -> dict[str, Any]:
+        return self._resources.get("SpawnPoint", {})
+
+    @property
+    def data_centers(self) -> dict[str, Any]:
+        return self._resources.get("DataCenters", {})
+
+    def worlds_for_data_centers(self, data_center_names: list[str]) -> list[str]:
+        worlds: list[str] = []
+        for name in data_center_names:
+            info = self.data_centers.get(name)
+            if not info:
+                continue
+            for world in info.get("Names", []):
+                if world not in worlds:
+                    worlds.append(world)
+        return worlds
+
+    def hunt_meta(self, hunt_key: str) -> dict[str, Any]:
+        meta = self.database_hunt.get(hunt_key)
+        if meta:
+            return meta
+        trimmed = hunt_key[:-2] if len(hunt_key) > 2 else hunt_key
+        return self.database_hunt.get(trimmed, {})
+
+    def spawn_map_key(self, hunt_key: str, meta: dict[str, Any]) -> str | None:
+        patch = meta.get("Patch", "")
+        region = meta.get("Region", "")
+        if patch == "DT" and hunt_key.startswith("Arch Aethereater "):
+            return f"Arch Aethereater {region}"
+        if patch == "EW" and hunt_key.startswith("Ker "):
+            return hunt_key
+        if patch == "ShB" and hunt_key.startswith("Forgiven Rebellion "):
+            return hunt_key
+        if hunt_key in self.spawn_point:
+            return hunt_key
+        return None

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/bear_tracker/spawn_points.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ff14_the_hunt.models import MapCoordinate
+
+
+def list_map_coordinates(
+    spawn_entry: dict[str, Any] | None,
+    *,
+    api_states: dict[str, Any] | None = None,
+) -> list[MapCoordinate]:
+    """从 ``resources.SpawnPoint`` 条目解析触发生点坐标。
+
+    Args:
+        spawn_entry: ``syncSession`` 内 ``SpawnPoint[huntKey]``。
+        api_states: ``querySpawnPoints`` 返回的各点状态（可选）。
+    """
+    if not spawn_entry:
+        return []
+    dimensions = spawn_entry.get("Dimensions") or [41, 41]
+    scale = float(dimensions[0]) if dimensions else 41.0
+    display_count = int(spawn_entry.get("DisplayPoints", 0))
+    coordinates: list[MapCoordinate] = []
+    point_items = sorted(
+        (
+            (key, value)
+            for key, value in spawn_entry.items()
+            if re.match(r"^SpawnPoint\d+$", key)
+        ),
+        key=lambda item: item[0],
+    )
+    for index, (key, raw) in enumerate(point_items):
+        if display_count and index >= display_count:
+            break
+        if not isinstance(raw, (list, tuple)) or len(raw) < 2:
+            continue
+        grid_x = float(raw[0])
+        grid_y = float(raw[1])
+        norm_x = (grid_x - 1.0) / scale
+        norm_y = (grid_y - 1.0) / scale
+        state = None
+        if api_states and key in api_states:
+            entry = api_states[key]
+            if isinstance(entry, dict):
+                state_val = entry.get("State")
+                if state_val is not None:
+                    state = bool(state_val)
+        coordinates.append(
+            MapCoordinate(
+                point_key=key,
+                x=norm_x,
+                y=norm_y,
+                grid_x=grid_x,
+                grid_y=grid_y,
+                active=state,
+            )
+        )
+    return coordinates

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/bear_tracker/spawn_window.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import time
+
+from ff14_the_hunt.models import SpawnWindowPhase, TimerDisplay
+
+
+def _format_duration(seconds: float) -> str:
+    total = max(0, int(seconds))
+    hours = total // 3600
+    minutes = (total % 3600) // 60
+    return f"{hours:02d}:{minutes:02d}"
+
+
+def compute_trigger_timer(
+    *,
+    respawn_hours: tuple[float, float],
+    last_death_time: float,
+    last_mark_time: float | None = None,
+    missing_counter: float = 0.0,
+    now: float | None = None,
+) -> TimerDisplay:
+    """复刻站点主计时列（组件 ``io``）的触发时间窗逻辑。
+
+    Args:
+        respawn_hours: ``(开窗延迟小时, 窗宽小时)``，来自 RespawnTimer 或 MaintTimer。
+        last_death_time: 上次死亡 Unix 秒。
+        last_mark_time: 有人标记发现时的时间；会收窄/平移开窗区间。
+        missing_counter: 与站点一致的失踪计数加权。
+        now: 当前 Unix 秒，默认 ``time.time()``。
+    """
+    if now is None:
+        now = time.time()
+    start_hours, window_hours = respawn_hours
+    now_ms = now * 1000.0
+    death_ms = last_death_time * 1000.0
+
+    if last_mark_time is not None and last_mark_time > 0:
+        mark_ms = last_mark_time * 1000.0
+        open_ms = (missing_counter + 1.0) * start_hours * 3_600_000.0 + death_ms
+        close_ms = window_hours * 3_600_000.0 + start_hours * 3_600_000.0 + mark_ms
+    else:
+        open_ms = start_hours * 3_600_000.0 + death_ms
+        close_ms = open_ms + window_hours * 3_600_000.0
+
+    if now_ms < open_ms:
+        remaining = (open_ms - now_ms) / 1000.0
+        return TimerDisplay(
+            label="trigger",
+            phase=SpawnWindowPhase.ALMOST_OPEN,
+            remaining_seconds=remaining,
+            summary=f"距离开窗 {_format_duration(remaining)}",
+        )
+
+    if now_ms < close_ms:
+        elapsed = (now_ms - open_ms) / 1000.0
+        span = (close_ms - open_ms) / 1000.0
+        progress = (elapsed / span * 100.0) if span > 0 else 0.0
+        return TimerDisplay(
+            label="trigger",
+            phase=SpawnWindowPhase.OPEN,
+            elapsed_seconds=elapsed,
+            progress_percent=min(progress, 999.0),
+            summary=f"已开窗 {_format_duration(elapsed)}（{progress:.0f}%）",
+        )
+
+    elapsed_since_cap = (now_ms - close_ms) / 1000.0
+    return TimerDisplay(
+        label="trigger",
+        phase=SpawnWindowPhase.CAPPED,
+        elapsed_seconds=elapsed_since_cap,
+        summary=f"已强制（cap） {_format_duration(elapsed_since_cap)}",
+    )
+
+
+def is_window_open(timer: TimerDisplay | None) -> bool:
+    return timer is not None and timer.phase == SpawnWindowPhase.OPEN
+
+
+def is_recently_in_window(
+    timer: TimerDisplay | None,
+    *,
+    grace_seconds: float = 900.0,
+) -> bool:
+    if timer is None or timer.phase != SpawnWindowPhase.OPEN:
+        return False
+    if timer.elapsed_seconds is None:
+        return False
+    return timer.elapsed_seconds <= grace_seconds

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/ff14_the_hunt.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from ff14_the_hunt.bear_tracker.client import BearTrackerClient
+from ff14_the_hunt.bear_tracker.enrich import build_hunt_record
+from ff14_the_hunt.bear_tracker.resources import BearResources
+from ff14_the_hunt.models import HuntMarkRecord, HuntQueryFilter, HuntRankKind
+
+
+class FF14TheHunt:
+    """FF14 狩猎追踪门面：当前对接 [Bear Tracker](https://tracker.beartoolkit.com/timer)。"""
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        timeout_seconds: float = 120.0,
+    ) -> None:
+        kwargs: dict[str, float | str] = {"timeout_seconds": timeout_seconds}
+        if base_url is not None:
+            kwargs["base_url"] = base_url
+        self._client = BearTrackerClient(**kwargs)
+        self._resources: BearResources | None = None
+
+    @property
+    def client(self) -> BearTrackerClient:
+        return self._client
+
+    def ensure_resources(self) -> BearResources:
+        if self._resources is None:
+            session = self._client.sync_session()
+            raw = session.get("resources", {})
+            self._resources = BearResources(raw)
+        return self._resources
+
+    def list_data_centers(self, *, region: str | None = None) -> list[str]:
+        """列出数据中心名；``region='CN'`` 仅中国区。"""
+        resources = self.ensure_resources()
+        names: list[str] = []
+        for name, info in resources.data_centers.items():
+            if region is not None and info.get("Region") != region:
+                continue
+            names.append(name)
+        return sorted(names)
+
+    def list_worlds(self, data_centers: list[str]) -> list[str]:
+        resources = self.ensure_resources()
+        return resources.worlds_for_data_centers(data_centers)
+
+    def query_marks(
+        self,
+        query: HuntQueryFilter,
+        *,
+        include_spawn_states: bool = False,
+        recent_grace_seconds: float = 900.0,
+    ) -> list[HuntMarkRecord]:
+        """按筛选条件查询并解析狩猎计时。
+
+        Args:
+            query: 数据中心、世界、Rank、资料片等筛选。
+            include_spawn_states: 为 True 时对每条记录请求 ``querySpawnPoints``（较慢）。
+            recent_grace_seconds: 开窗或标记后多少秒内视为「刚刷新」。
+        """
+        resources = self.ensure_resources()
+        worlds = list(query.worlds)
+        if not worlds:
+            worlds = resources.worlds_for_data_centers(query.data_centers)
+        if not worlds:
+            return []
+
+        rows: list[dict] = []
+        for rank in query.rank_kinds:
+            rows.extend(
+                self._client.last_death_timers(
+                    world_names=worlds,
+                    rank_type=rank.value,
+                )
+            )
+
+        records: list[HuntMarkRecord] = []
+        for row in rows:
+            spawn_states = None
+            if include_spawn_states:
+                spawn_states = self._load_spawn_states(row, resources)
+            record = build_hunt_record(
+                timer_row=row,
+                resources=resources,
+                spawn_states=spawn_states,
+                query=query,
+                recent_grace_seconds=recent_grace_seconds,
+            )
+            if record is not None:
+                records.append(record)
+        return records
+
+    def recently_spawned(
+        self,
+        query: HuntQueryFilter,
+        *,
+        recent_grace_seconds: float = 900.0,
+    ) -> list[HuntMarkRecord]:
+        marks = self.query_marks(
+            query,
+            recent_grace_seconds=recent_grace_seconds,
+        )
+        return [mark for mark in marks if mark.recently_spawned]
+
+    def _load_spawn_states(
+        self,
+        row: dict,
+        resources: BearResources,
+    ) -> dict | None:
+        hunt_key = str(row.get("huntKey") or "")
+        world_name = str(row.get("worldName") or "")
+        if not hunt_key or not world_name:
+            return None
+        meta = resources.hunt_meta(hunt_key)
+        last_death = row.get("lastMarkTime") or row.get("lastDeathTime")
+        try:
+            states = self._client.query_spawn_points(
+                hunt_name=hunt_key,
+                world_name=world_name,
+                last_death=float(last_death) if last_death else None,
+            )
+        except RuntimeError:
+            return None
+        return states if isinstance(states, dict) else None

python_library_ff14_the_hunt-0.0.0/ff14_the_hunt/models.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class HuntRankKind(str, Enum):
+    """Bear Tracker ``lastDeathTimers`` 的 ``RankType`` 取值。"""
+
+    A = "aRank"
+    S = "sRank"
+    FATE = "fate"
+
+
+class SpawnWindowPhase(str, Enum):
+    """与站点主计时条颜色/文案一致的开窗阶段。"""
+
+    CLOSED = "closed"
+    ALMOST_OPEN = "almost_open"
+    OPEN = "open"
+    CAPPED = "capped"
+
+
+class MapCoordinate(BaseModel):
+    """地图格点坐标（与站点触发的地图一致，非游戏内绝对坐标）。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    point_key: str = Field(description="SpawnPoint 键名，例如 SpawnPoint01")
+    x: float = Field(description="地图 X，已按站点公式归一化")
+    y: float = Field(description="地图 Y，已按站点公式归一化")
+    grid_x: float | None = Field(default=None, description="原始格点 X")
+    grid_y: float | None = Field(default=None, description="原始格点 Y")
+    active: bool | None = Field(default=None, description="querySpawnPoints 返回的存活点位状态")
+
+
+class TimerDisplay(BaseModel):
+    """单条计时展示（触发窗或条件窗）。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    label: str = Field(description="例如 trigger / condition / fate")
+    phase: SpawnWindowPhase | None = Field(default=None)
+    elapsed_seconds: float | None = Field(default=None)
+    remaining_seconds: float | None = Field(default=None)
+    progress_percent: float | None = Field(default=None)
+    summary: str = Field(default="", description="人类可读简述")
+
+
+class HuntMarkRecord(BaseModel):
+    """单条狩猎计时记录（合并 API 与资源库后的视图）。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    hunt_key: str
+    hunt_name: str
+    world_name: str
+    region: str | list[str] = ""
+    patch: str = ""
+    rank: int | None = None
+    last_death_time: float | None = None
+    last_mark_time: float | None = None
+    missing_counter: float = 0.0
+    is_maintenance: bool = False
+    fate_last_seen: float | None = None
+    fate_last_death: float | None = None
+    trigger_timer: TimerDisplay | None = None
+    condition_timer: TimerDisplay | None = None
+    spawn_points: list[MapCoordinate] = Field(default_factory=list)
+    recently_spawned: bool = False
+    raw_timer: dict[str, Any] = Field(default_factory=dict)
+
+
+class HuntQueryFilter(BaseModel):
+    """查询 Bear Tracker 时的筛选条件。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    data_centers: list[str] = Field(
+        default_factory=list,
+        description="中国区为猫小胖、莫古力等数据中心名；国际区为 Aether 等",
+    )
+    worlds: list[str] = Field(
+        default_factory=list,
+        description="世界名；为空时由 data_centers 展开全部世界",
+    )
+    rank_kinds: list[HuntRankKind] = Field(
+        default_factory=lambda: [HuntRankKind.S],
+        description="A / S / FATE，可多选",
+    )
+    patches: list[str] = Field(
+        default_factory=list,
+        description="资料片缩写：ARR、HW、ShB、EW、DT 等；空表示不过滤",
+    )
+    hunt_keys: list[str] = Field(
+        default_factory=list,
+        description="限定 huntKey；空表示不过滤",
+    )
+    regions: list[str] = Field(
+        default_factory=list,
+        description="地图区域名；空表示不过滤",
+    )

python_library_ff14_the_hunt-0.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-ff14-the-hunt"
+version = "0.0.0"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ff14_the_hunt"]

python_library_ff14_the_hunt-0.0.0/test.bat

@@ -0,0 +1,9 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    call update.bat
+)
+
+call .venv\Scripts\activate.bat
+python -m unittest discover -s tests -p "test_*.py"

python_library_ff14_the_hunt-0.0.0/tests/test_spawn_window.py

@@ -0,0 +1,16 @@
+from ff14_the_hunt.bear_tracker.spawn_window import (
+    SpawnWindowPhase,
+    compute_trigger_timer,
+)
+
+
+def test_trigger_window_open() -> None:
+    last_death = 1_000_000.0
+    timer = compute_trigger_timer(
+        respawn_hours=(1.0, 2.0),
+        last_death_time=last_death,
+        now=last_death + 3600 + 60,
+    )
+    assert timer.phase == SpawnWindowPhase.OPEN
+    assert timer.progress_percent is not None
+    assert timer.progress_percent > 0

python_library_ff14_the_hunt-0.0.0/update.bat

@@ -0,0 +1,9 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .