HV-BIE（HV Battle Intelligence Extractor）
將 HentaiVerse 戰鬥頁面的 HTML 原始碼字串解析為結構化的 Python 資料類別（dataclasses）。
- 支援環境：Python 3.14
- 主要相依：beautifulsoup4>=4.15.0
- 套件名稱：
hv_bie - 發佈名稱（PyPI）：
hv-bie；匯入名稱（Python）：hv_bie
更多介面與資料模型細節，請參考：
- API 規格書：
API_SPEC.md - 軟體需求規格：
SRS.md
功能一覽
依據 SRS 的功能需求（FR-1 ~ FR-7），本套件可從單一 HV 戰鬥頁面 HTML 中抽取：
- 玩家資源（HP/MP/SP 百分比與數值、Overcharge 整數值）
- 玩家 Buff/Debuff（名稱、剩餘時間或永久旗標）
- 技能與法術清單（可用狀態、成本/冷卻若可推知）
- 怪物清單（名稱、是否存活、資源百分比、系統怪物類型、怪物 Buff）
- 戰鬥文字紀錄（由舊到新），含目前/總回合數（若頁面有顯示）
- 道具與快捷列（名稱、槽位、可用狀態）
解析結果以單一「戰鬥快照」物件回傳，確保同一份 HTML 的各區塊資訊彼此一致。
安裝
可以透過 PyPI 安裝，或從原始碼安裝：
# 從 PyPI 安裝（若已發布）
pip install hv-bie
# 或在專案根目錄從原始碼安裝
pip install -e .
快速上手
from hv_bie import parse_snapshot
from hv_bie.types.models import BattleSnapshot
from pathlib import Path
# 讀取你的戰鬥頁面 HTML（字串）
html = Path("tests/fixtures/hv/The HentaiVerse.htm").read_text(encoding="utf-8")
snap: BattleSnapshot = parse_snapshot(html)
# 玩家資訊
print(snap.player.hp_value, snap.player.hp_percent)
print("Spirit Stance" in snap.player.buffs)
# 技能/法術
for name, sk in snap.abilities.skills.items():
print(name, sk.available, sk.cost_type, sk.cost, sk.cooldown_turns)
# 怪物清單
for idx, m in snap.monsters.items():
print(idx, m.name, m.alive, m.system_monster_type, m.hp_percent)
# 戰報（由舊到新）與回合資訊
print(snap.log.current_round, "/", snap.log.total_round)
print(snap.log.lines[0], "->", snap.log.lines[-1])
# 道具與快捷列
print("Health Draught" in snap.items.items)
print(len(snap.items.quickbar))
# 序列化
print(snap.as_dict())
print(snap.to_json())
公開 API（最小穩定面）
from hv_bie import parse_snapshot
from hv_bie.types import BattleSnapshot
def parse_snapshot(html: str) -> BattleSnapshot: ...
parse_snapshot(html: str) -> BattleSnapshot- 從單一戰鬥頁面 HTML 產生一次「戰鬥快照」。
- 容錯：若頁面某區塊缺漏，不丟例外；以預設值補齊，並在
BattleSnapshot.warnings累積文字告警。
更多說明請參考 API_SPEC.md。
資料模型（概要）
主要 dataclasses 定義於 hv_bie/types/models.py，鍵名與型別視為穩定契約：
BattleSnapshotplayer: PlayerStateabilities: AbilitiesStatemonsters: dict[int, Monster]log: CombatLogitems: ItemsStatewarnings: list[str]as_dict() -> dict/to_json() -> str
PlayerState：HP/MP/SP 百分比與數值、Overcharge 整數值、玩家 BuffAbilitiesState：skills/spells（各為dict[str, Ability]）Monster：插槽序號、名稱、是否存活、系統怪物類型、各資源百分比、BuffCombatLog：lines（由舊到新）、current_round、total_roundItemsState：items（道具字典）、quickbar（快捷列清單）
系統怪物對照可參考 hv_bie/types/system_monsters.py 提供的查詢輔助。
容錯與告警
- 解析不會因缺漏 DOM 區塊而失敗；以預設值/空集合回傳。
- 告警文字會累積於
BattleSnapshot.warnings（例如："pane_vitals not found"、"table_skills not found"）。 - 呼叫端可依告警採取重試或記錄行為。
效能與非功能性
- 目標（NFR-P1）：在一般桌機上解析單頁應具互動式體驗（建議目標 ≲ 50ms，實測見
tests/perf/）。 - 相依精簡：僅使用 BeautifulSoup（bs4）。
- 安全：僅解析字串，不執行頁面腳本、不進行任何網路互動。
更多 NFR 請見 SRS.md。
相容性
- Python 3.14
- 作業系統不限（純 Python，OS Independent）
測試與驗證
本庫提供單元與整合測試，樣本 HTML 置於 tests/fixtures/hv/。
# 執行測試
python -m pytest -q
重要測試：
- 單元測試：
tests/unit/test_parsers.py - 整合測試：
tests/unit/test_snapshot_integration.py - 效能測試：
tests/perf/test_nfr_p1_performance.py
版本與文件
- 目前版本：
0.3.2（見pyproject.toml） - 變更紀錄：
CHANGELOG.md - 規格文件：
API_SPEC.md、SRS.md
LICENSE
本專案以 AGPL-3.0-or-later 授權釋出。詳見檔案：LICENSE。
1 maintainer
Metadata
1 maintainer
Release files for hv-bie 0.7.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| hv_bie-0.7.3.tar.gz | 671.7 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hv_bie-0.7.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 695.5 kB
Release files / hv_bie-0.7.3.tar.gz
| Download URL | hv_bie-0.7.3.tar.gz |
|---|---|
| Size | 671.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e5d257e9fdcba184d6ca2271562ddccfedc200b43a41b7ef7e1a4098abe37aea
|
|
BLAKE2b-256 checksum How to use checksums |
a4a6d47119735d6345ebeace4b964613d654198e15127a405fd7ad69fe6be7c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency logRelease files / hv_bie-0.7.3-py3-none-any.whl
| Download URL | hv_bie-0.7.3-py3-none-any.whl |
|---|---|
| Size | 23.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ab5595d2806c65d4523de85c31785f0da466429f7e73a1be13a92b31d9d75fb
|
|
BLAKE2b-256 checksum How to use checksums |
5110ecac916f1e48cf8ca1e1a4fbe6f895df3cca70c5835eb94b91ff113dad36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency logSecurity for hv-bie 0.7.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for hv_bie-0.7.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
