python-library-ff14-the-hunt 0.0.9__tar.gz → 0.0.10__tar.gz

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/.cursor/skills/ff14_the_hunt-package-changelog/SKILL.md

@@ -7,6 +7,10 @@ description: ff14_the_hunt 包：要求与决议；最新在上。
 
 （规则见 `~/.cursor/skills/agent-project-changelog/SKILL.md`。）
 
+## 2026-07-19
+
+- **Decision**: polling reports the first observed trigger-window `OPEN` event once per hunt/world/death cycle. `HuntMarkRecord.newly_opened` distinguishes the open-window event, and `newly_spawned` remains the compatibility signal for report-worthy messages so existing ff14hub callbacks that read `newly_spawned_marks` do not miss the 100% open-window transition.
+
 ## 2026-06-10
 
 - **决议**：自动轮询：爬取、回调或循环内任意异常均记录后等待 60 秒继续，仅 ``KeyboardInterrupt`` / ``SystemExit`` 可终止服务。发布 ``0.0.6``。

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-library-ff14-the-hunt
-Version: 0.0.9
+Version: 0.0.10
 Requires-Python: >=3.10
 Requires-Dist: pydantic>=2.0
 Provides-Extra: dev

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/bear_tracker/client.py

@@ -1,74 +1,74 @@
 from __future__ import annotations
 
-import json
-import threading
-import time
-import urllib.error
-import urllib.request
-from typing import Any
-
-from ff14_the_hunt.common.urlopen_retry import (
-    retry_after_seconds_from_headers,
-    urlopen_read,
-)
-from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
-
-DEFAULT_BASE_URL = "https://tracker.beartoolkit.com/api"
-_BLOCKED_HTTP_CODES = frozenset({403, 429})
-
-
-class BearTrackerRequestError(RuntimeError):
-    """Bear Tracker API request failed after HTTP retry handling."""
-
-    def __init__(
-        self,
-        message: str,
-        *,
-        status_code: int | None = None,
-        retry_after_seconds: float | None = None,
-    ) -> None:
-        super().__init__(message)
-        self.status_code = status_code
-        self.retry_after_seconds = retry_after_seconds
-
-
-class BearTrackerBlockedError(BearTrackerRequestError):
-    """Bear Tracker returned a block or rate-limit status."""
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from ff14_the_hunt.common.urlopen_retry import (
+    retry_after_seconds_from_headers,
+    urlopen_read,
+)
+from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
+
+DEFAULT_BASE_URL = "https://tracker.beartoolkit.com/api"
+_BLOCKED_HTTP_CODES = frozenset({403, 429})
+
+
+class BearTrackerRequestError(RuntimeError):
+    """Bear Tracker API request failed after HTTP retry handling."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.retry_after_seconds = retry_after_seconds
+
+
+class BearTrackerBlockedError(BearTrackerRequestError):
+    """Bear Tracker returned a block or rate-limit status."""
 
 
 class BearTrackerClient:
     """Bear Tracker 站点同源 API 客户端（``/api/*``）。"""
 
-    def __init__(
-        self,
-        *,
-        base_url: str = DEFAULT_BASE_URL,
-        timeout_seconds: float = 120.0,
-        min_request_interval_seconds: float = 1.0,
-        user_agent: str = DEFAULT_USER_AGENT,
-    ) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._timeout_seconds = timeout_seconds
-        self._min_request_interval_seconds = min_request_interval_seconds
-        self._user_agent = user_agent
-        self._last_request_at = 0.0
-        self._request_lock = threading.Lock()
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_seconds: float = 120.0,
+        min_request_interval_seconds: float = 1.0,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout_seconds = timeout_seconds
+        self._min_request_interval_seconds = min_request_interval_seconds
+        self._user_agent = user_agent
+        self._last_request_at = 0.0
+        self._request_lock = threading.Lock()
 
     @property
     def base_url(self) -> str:
         return self._base_url
 
     @property
-    def timeout_seconds(self) -> float:
-        return self._timeout_seconds
-
-    @property
-    def min_request_interval_seconds(self) -> float:
-        return self._min_request_interval_seconds
-
-    @property
-    def user_agent(self) -> str:
-        return self._user_agent
+    def timeout_seconds(self) -> float:
+        return self._timeout_seconds
+
+    @property
+    def min_request_interval_seconds(self) -> float:
+        return self._min_request_interval_seconds
+
+    @property
+    def user_agent(self) -> str:
+        return self._user_agent
 
     def sync_session(self) -> dict[str, Any]:
         """拉取会话与 ``resources``（含 DatabaseHunt、SpawnPoint、DataCenters）。"""
@@ -123,57 +123,57 @@ class BearTrackerClient:
             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=self._headers(),
-            method="POST",
-        )
-        try:
-            self._pace_request()
-            raw = urlopen_read(request, timeout=self._timeout_seconds)
-        except urllib.error.HTTPError as exc:
-            detail = exc.read().decode("utf-8", errors="replace")
-            retry_after = retry_after_seconds_from_headers(exc.headers)
-            message = f"Bear Tracker API {path} failed: HTTP {exc.code}: {detail}"
-            error_type = (
-                BearTrackerBlockedError
-                if exc.code in _BLOCKED_HTTP_CODES
-                else BearTrackerRequestError
-            )
-            raise error_type(
-                message,
-                status_code=exc.code,
-                retry_after_seconds=retry_after,
-            ) from exc
-        except urllib.error.URLError as exc:
-            raise BearTrackerRequestError(f"Bear Tracker API {path} failed: {exc}") from exc
-        parsed = json.loads(raw.decode("utf-8"))
-        if not isinstance(parsed, dict):
-            raise RuntimeError(f"unexpected response type from {path}")
-        return parsed
-
-    def _headers(self) -> dict[str, str]:
-        return {
-            "User-Agent": self._user_agent,
-            "Content-Type": "application/json",
-            "Accept": "application/json, text/plain, */*",
-            "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
-            "Origin": "https://tracker.beartoolkit.com",
-            "Referer": "https://tracker.beartoolkit.com/timer",
-        }
-
-    def _pace_request(self) -> None:
-        if self._min_request_interval_seconds <= 0:
-            return
-        with self._request_lock:
-            now = time.monotonic()
-            wait_seconds = self._min_request_interval_seconds - (
-                now - self._last_request_at
-            )
-            if wait_seconds > 0:
-                time.sleep(wait_seconds)
-            self._last_request_at = time.monotonic()
+    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=self._headers(),
+            method="POST",
+        )
+        try:
+            self._pace_request()
+            raw = urlopen_read(request, timeout=self._timeout_seconds)
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            retry_after = retry_after_seconds_from_headers(exc.headers)
+            message = f"Bear Tracker API {path} failed: HTTP {exc.code}: {detail}"
+            error_type = (
+                BearTrackerBlockedError
+                if exc.code in _BLOCKED_HTTP_CODES
+                else BearTrackerRequestError
+            )
+            raise error_type(
+                message,
+                status_code=exc.code,
+                retry_after_seconds=retry_after,
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise BearTrackerRequestError(f"Bear Tracker API {path} failed: {exc}") from exc
+        parsed = json.loads(raw.decode("utf-8"))
+        if not isinstance(parsed, dict):
+            raise RuntimeError(f"unexpected response type from {path}")
+        return parsed
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "User-Agent": self._user_agent,
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/plain, */*",
+            "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+            "Origin": "https://tracker.beartoolkit.com",
+            "Referer": "https://tracker.beartoolkit.com/timer",
+        }
+
+    def _pace_request(self) -> None:
+        if self._min_request_interval_seconds <= 0:
+            return
+        with self._request_lock:
+            now = time.monotonic()
+            wait_seconds = self._min_request_interval_seconds - (
+                now - self._last_request_at
+            )
+            if wait_seconds > 0:
+                time.sleep(wait_seconds)
+            self._last_request_at = time.monotonic()

python_library_ff14_the_hunt-0.0.10/ff14_the_hunt/common/http_request.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+DEFAULT_USER_AGENT = "ff14-the-hunt/0.0.9"

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/common/urlopen_retry.py

@@ -1,39 +1,39 @@
 from __future__ import annotations
 
-import ssl
-import time
-import urllib.error
-import urllib.request
-from collections.abc import Callable
-from email.utils import parsedate_to_datetime
-from random import uniform
+import ssl
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from email.utils import parsedate_to_datetime
+from random import uniform
 
 _RETRYABLE_HTTP_CODES = frozenset({408, 429, 500, 502, 503, 504})
-_DEFAULT_MAX_ATTEMPTS = 4
-_DEFAULT_INITIAL_BACKOFF_SECONDS = 1.0
-_DEFAULT_MAX_BACKOFF_SECONDS = 8.0
-_DEFAULT_MAX_RETRY_AFTER_SECONDS = 300.0
-_DEFAULT_JITTER_RATIO = 0.15
-
-
-def retry_after_seconds_from_headers(headers: object) -> float | None:
-    if headers is None or not hasattr(headers, "get"):
-        return None
-    raw = headers.get("Retry-After")  # type: ignore[attr-defined]
-    if raw is None:
-        return None
-    text = str(raw).strip()
-    if not text:
-        return None
-    try:
-        seconds = float(text)
-    except ValueError:
-        try:
-            retry_at = parsedate_to_datetime(text)
-        except (TypeError, ValueError):
-            return None
-        seconds = retry_at.timestamp() - time.time()
-    return max(0.0, seconds)
+_DEFAULT_MAX_ATTEMPTS = 4
+_DEFAULT_INITIAL_BACKOFF_SECONDS = 1.0
+_DEFAULT_MAX_BACKOFF_SECONDS = 8.0
+_DEFAULT_MAX_RETRY_AFTER_SECONDS = 300.0
+_DEFAULT_JITTER_RATIO = 0.15
+
+
+def retry_after_seconds_from_headers(headers: object) -> float | None:
+    if headers is None or not hasattr(headers, "get"):
+        return None
+    raw = headers.get("Retry-After")  # type: ignore[attr-defined]
+    if raw is None:
+        return None
+    text = str(raw).strip()
+    if not text:
+        return None
+    try:
+        seconds = float(text)
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(text)
+        except (TypeError, ValueError):
+            return None
+        seconds = retry_at.timestamp() - time.time()
+    return max(0.0, seconds)
 
 
 def is_retryable_urlopen_error(exc: BaseException) -> bool:
@@ -54,17 +54,17 @@ def is_retryable_urlopen_error(exc: BaseException) -> bool:
     return False
 
 
-def urlopen_read(
-    request: urllib.request.Request,
-    *,
-    timeout: float,
-    max_attempts: int = _DEFAULT_MAX_ATTEMPTS,
-    initial_backoff_seconds: float = _DEFAULT_INITIAL_BACKOFF_SECONDS,
-    max_backoff_seconds: float = _DEFAULT_MAX_BACKOFF_SECONDS,
-    max_retry_after_seconds: float = _DEFAULT_MAX_RETRY_AFTER_SECONDS,
-    jitter_ratio: float = _DEFAULT_JITTER_RATIO,
-    sleep: Callable[[float], None] = time.sleep,
-) -> bytes:
+def urlopen_read(
+    request: urllib.request.Request,
+    *,
+    timeout: float,
+    max_attempts: int = _DEFAULT_MAX_ATTEMPTS,
+    initial_backoff_seconds: float = _DEFAULT_INITIAL_BACKOFF_SECONDS,
+    max_backoff_seconds: float = _DEFAULT_MAX_BACKOFF_SECONDS,
+    max_retry_after_seconds: float = _DEFAULT_MAX_RETRY_AFTER_SECONDS,
+    jitter_ratio: float = _DEFAULT_JITTER_RATIO,
+    sleep: Callable[[float], None] = time.sleep,
+) -> bytes:
     """``urlopen`` 读响应体；瞬时网络或 TLS 失败时指数退避重试。
 
     Args:
@@ -82,12 +82,12 @@ def urlopen_read(
         urllib.error.URLError: 重试耗尽后的网络或 TLS 错误。
         TimeoutError: 重试耗尽后的超时。
     """
-    if max_attempts < 1:
-        raise ValueError("max_attempts must be >= 1")
-    if max_retry_after_seconds < 0:
-        raise ValueError("max_retry_after_seconds must be >= 0")
-    if jitter_ratio < 0:
-        raise ValueError("jitter_ratio must be >= 0")
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+    if max_retry_after_seconds < 0:
+        raise ValueError("max_retry_after_seconds must be >= 0")
+    if jitter_ratio < 0:
+        raise ValueError("jitter_ratio must be >= 0")
 
     last_exc: BaseException | None = None
     backoff = initial_backoff_seconds
@@ -96,18 +96,18 @@ def urlopen_read(
             with urllib.request.urlopen(request, timeout=timeout) as response:
                 return response.read()
         except BaseException as exc:
-            last_exc = exc
-            if attempt + 1 >= max_attempts or not is_retryable_urlopen_error(exc):
-                raise
-            wait_seconds = min(backoff, max_backoff_seconds)
-            if isinstance(exc, urllib.error.HTTPError):
-                retry_after = retry_after_seconds_from_headers(exc.headers)
-                if retry_after is not None:
-                    wait_seconds = min(retry_after, max_retry_after_seconds)
-            if jitter_ratio > 0 and wait_seconds > 0:
-                wait_seconds *= uniform(1.0 - jitter_ratio, 1.0 + jitter_ratio)
-            sleep(wait_seconds)
-            backoff = min(backoff * 2.0, max_backoff_seconds)
+            last_exc = exc
+            if attempt + 1 >= max_attempts or not is_retryable_urlopen_error(exc):
+                raise
+            wait_seconds = min(backoff, max_backoff_seconds)
+            if isinstance(exc, urllib.error.HTTPError):
+                retry_after = retry_after_seconds_from_headers(exc.headers)
+                if retry_after is not None:
+                    wait_seconds = min(retry_after, max_retry_after_seconds)
+            if jitter_ratio > 0 and wait_seconds > 0:
+                wait_seconds *= uniform(1.0 - jitter_ratio, 1.0 + jitter_ratio)
+            sleep(wait_seconds)
+            backoff = min(backoff * 2.0, max_backoff_seconds)
 
     if last_exc is not None:
         raise last_exc

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/ff14_the_hunt.py

@@ -5,14 +5,14 @@ import threading
 import time
 from collections.abc import Callable
 
-from ff14_the_hunt.bear_tracker.client import (
-    BearTrackerBlockedError,
-    BearTrackerClient,
-)
-from ff14_the_hunt.bear_tracker.enrich import build_hunt_record, mark_has_display_timer
-from ff14_the_hunt.bear_tracker.resources import BearResources
-from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
-from ff14_the_hunt.locale.cn import normalize_patch_codes
+from ff14_the_hunt.bear_tracker.client import (
+    BearTrackerBlockedError,
+    BearTrackerClient,
+)
+from ff14_the_hunt.bear_tracker.enrich import build_hunt_record, mark_has_display_timer
+from ff14_the_hunt.bear_tracker.resources import BearResources
+from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
+from ff14_the_hunt.locale.cn import normalize_patch_codes
 from ff14_the_hunt.models import (
     HuntCrawlPacket,
     HuntMarkRecord,
@@ -26,9 +26,9 @@ from ff14_the_hunt.spawn_map.region_fetch import RegionMapFetcher, site_root_fro
 
 HuntCrawlCallback = Callable[[HuntCrawlPacket], None]
 
-_log = logging.getLogger(__name__)
-_FETCH_FAILURE_RETRY_SECONDS = 60.0
-_BLOCKED_RETRY_SECONDS = 900.0
+_log = logging.getLogger(__name__)
+_FETCH_FAILURE_RETRY_SECONDS = 60.0
+_BLOCKED_RETRY_SECONDS = 900.0
 
 
 class FF14TheHunt:
@@ -42,12 +42,12 @@ class FF14TheHunt:
         rank_kinds: list[HuntRankKind] | None = None,
         patches: list[str] | None = None,
         hunt_keys: list[str] | None = None,
-        regions: list[str] | None = None,
-        base_url: str | None = None,
-        timeout_seconds: float = 120.0,
-        min_request_interval_seconds: float = 1.0,
-        user_agent: str = DEFAULT_USER_AGENT,
-        active_poll_interval_seconds: float = 600.0,
+        regions: list[str] | None = None,
+        base_url: str | None = None,
+        timeout_seconds: float = 120.0,
+        min_request_interval_seconds: float = 1.0,
+        user_agent: str = DEFAULT_USER_AGENT,
+        active_poll_interval_seconds: float = 600.0,
         recent_poll_interval_seconds: float = 300.0,
         fallback_poll_interval_seconds: float = 1800.0,
         min_wakeup_seconds: float = 120.0,
@@ -78,11 +78,11 @@ class FF14TheHunt:
             include_spawn_maps: 为刚刷新记录拉取站点区域原图 PNG base64。
             include_untimed_marks: 是否保留无计时的占位行（SS 级噬灵王、维护占位等）。
         """
-        kwargs: dict[str, float | str] = {
-            "timeout_seconds": timeout_seconds,
-            "min_request_interval_seconds": min_request_interval_seconds,
-            "user_agent": user_agent,
-        }
+        kwargs: dict[str, float | str] = {
+            "timeout_seconds": timeout_seconds,
+            "min_request_interval_seconds": min_request_interval_seconds,
+            "user_agent": user_agent,
+        }
         if base_url is not None:
             kwargs["base_url"] = base_url
         self._client = BearTrackerClient(**kwargs)
@@ -299,12 +299,12 @@ class FF14TheHunt:
 
     def _region_map_fetcher(self) -> RegionMapFetcher:
         if self._map_fetcher is None:
-            self._map_fetcher = RegionMapFetcher(
-                site_root=site_root_from_api_base(self._client.base_url),
-                timeout_seconds=self._client.timeout_seconds,
-                min_request_interval_seconds=self._client.min_request_interval_seconds,
-                user_agent=self._client.user_agent,
-            )
+            self._map_fetcher = RegionMapFetcher(
+                site_root=site_root_from_api_base(self._client.base_url),
+                timeout_seconds=self._client.timeout_seconds,
+                min_request_interval_seconds=self._client.min_request_interval_seconds,
+                user_agent=self._client.user_agent,
+            )
         return self._map_fetcher
 
     def recently_spawned(
@@ -353,21 +353,21 @@ class FF14TheHunt:
             marks = self._scheduler.fetch()
         except (KeyboardInterrupt, SystemExit):
             raise
-        except BearTrackerBlockedError as exc:
-            retry_seconds = (
-                exc.retry_after_seconds
-                if exc.retry_after_seconds is not None
-                else _BLOCKED_RETRY_SECONDS
-            )
-            retry_seconds = max(retry_seconds, _FETCH_FAILURE_RETRY_SECONDS)
-            _log.warning(
-                "Bear Tracker refused crawl; retry in %s seconds: %s",
-                retry_seconds,
-                exc,
-            )
-            wait_or_stop(stop_event, retry_seconds)
-            return
-        except Exception as exc:
+        except BearTrackerBlockedError as exc:
+            retry_seconds = (
+                exc.retry_after_seconds
+                if exc.retry_after_seconds is not None
+                else _BLOCKED_RETRY_SECONDS
+            )
+            retry_seconds = max(retry_seconds, _FETCH_FAILURE_RETRY_SECONDS)
+            _log.warning(
+                "Bear Tracker refused crawl; retry in %s seconds: %s",
+                retry_seconds,
+                exc,
+            )
+            wait_or_stop(stop_event, retry_seconds)
+            return
+        except Exception as exc:
             _log.warning("狩猎爬取失败，%s 秒后重试：%s", _FETCH_FAILURE_RETRY_SECONDS, exc)
             wait_or_stop(stop_event, _FETCH_FAILURE_RETRY_SECONDS)
             return

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/locale/cn.py

@@ -121,10 +121,11 @@ def mark_to_display_dict(
         "上次死亡时间": mark.last_death_time,
         "上次标记时间": mark.last_mark_time,
         "失踪计数": mark.missing_counter,
-        "维护计时": mark.is_maintenance,
-        "刚刷新": mark.recently_spawned,
-        "新检出": mark.newly_spawned,
-    }
+        "维护计时": mark.is_maintenance,
+        "刚刷新": mark.recently_spawned,
+        "刚开窗": mark.newly_opened,
+        "新检出": mark.newly_spawned,
+    }
     if mark.fate_last_seen is not None:
         item["FATE最近发现"] = mark.fate_last_seen
     if mark.fate_last_death is not None:

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/locale/en.py

@@ -108,10 +108,11 @@ def mark_to_display_dict(
         "last_death_time": mark.last_death_time,
         "last_mark_time": mark.last_mark_time,
         "missing_counter": mark.missing_counter,
-        "is_maintenance": mark.is_maintenance,
-        "recently_spawned": mark.recently_spawned,
-        "newly_spawned": mark.newly_spawned,
-    }
+        "is_maintenance": mark.is_maintenance,
+        "recently_spawned": mark.recently_spawned,
+        "newly_opened": mark.newly_opened,
+        "newly_spawned": mark.newly_spawned,
+    }
     if mark.fate_last_seen is not None:
         item["fate_last_seen"] = mark.fate_last_seen
     if mark.fate_last_death is not None:

{python_library_ff14_the_hunt-0.0.9 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/models.py

@@ -137,11 +137,15 @@ class HuntMarkRecord(BaseModel):
         default=None,
         description="仅刚刷新且启用区域原图时填充",
     )
-    recently_spawned: bool = False
-    newly_spawned: bool = Field(
-        default=False,
-        description="本轮会话内首次检出的刚刷新；同一死亡周期不重复为 True",
-    )
+    recently_spawned: bool = False
+    newly_opened: bool = Field(
+        default=False,
+        description="First reported trigger-window open event in this polling session.",
+    )
+    newly_spawned: bool = Field(
+        default=False,
+        description="First report-worthy event in this polling session.",
+    )
     raw_timer: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -193,6 +197,10 @@ class HuntCrawlPacket(BaseModel):
     marks: list[HuntMarkRecord] = Field(default_factory=list, description="解析后的狩猎记录")
     query: HuntQueryFilter = Field(description="本次爬取使用的筛选条件")
 
-    @property
-    def newly_spawned_marks(self) -> list[HuntMarkRecord]:
-        return [mark for mark in self.marks if mark.newly_spawned]
+    @property
+    def newly_spawned_marks(self) -> list[HuntMarkRecord]:
+        return [mark for mark in self.marks if mark.newly_spawned]
+
+    @property
+    def newly_opened_marks(self) -> list[HuntMarkRecord]:
+        return [mark for mark in self.marks if mark.newly_opened]

python_library_ff14_the_hunt-0.0.10/ff14_the_hunt/poll/spawn_dedup.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from ff14_the_hunt.models import HuntMarkRecord, SpawnWindowPhase
+
+SpawnCycleKey = tuple[str, str, float | None]
+
+
+def spawn_cycle_key(mark: HuntMarkRecord) -> SpawnCycleKey:
+    """Return the per-hunt death cycle used for one-shot reports."""
+    return (mark.hunt_key, mark.world_name, mark.last_death_time)
+
+
+class SpawnReportTracker:
+    """Track one-shot report events across polling rounds."""
+
+    def __init__(self) -> None:
+        self._reported_spawn_cycles: set[SpawnCycleKey] = set()
+        self._reported_open_cycles: set[SpawnCycleKey] = set()
+
+    def apply(self, marks: list[HuntMarkRecord]) -> None:
+        for mark in marks:
+            cycle = spawn_cycle_key(mark)
+            mark.newly_opened = self._should_report_open_window(mark, cycle)
+            mark.newly_spawned = self._should_report_spawn(mark, cycle) or mark.newly_opened
+
+    def _should_report_spawn(self, mark: HuntMarkRecord, cycle: SpawnCycleKey) -> bool:
+        if not mark.recently_spawned:
+            return False
+        if cycle in self._reported_spawn_cycles:
+            return False
+        self._reported_spawn_cycles.add(cycle)
+        return True
+
+    def _should_report_open_window(self, mark: HuntMarkRecord, cycle: SpawnCycleKey) -> bool:
+        trigger = mark.trigger_timer
+        if trigger is None or trigger.phase != SpawnWindowPhase.OPEN:
+            return False
+        if cycle in self._reported_open_cycles:
+            return False
+        self._reported_open_cycles.add(cycle)
+        return True