session.py 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173
  1. from __future__ import annotations
  2. """页面导航的任务级运行时 session。"""
  3. from dataclasses import dataclass, field
  4. from tasks.GameUi.page_definition import Page, Transition
  5. from tasks.GameUi.registry import PageRegistry
  6. @dataclass
  7. class NavigatorSession:
  8. """当前任务的导航运行时上下文。
  9. Attributes:
  10. task_category: 当前任务所属分类。
  11. current_page: 最近一次稳定识别到的当前页面。
  12. edge_penalties: 边失败惩罚值,key 为边 key。
  13. local_unknown_closers: 当前任务追加的未知页关闭动作。
  14. pages: 当前任务 session 中可见的页面快照。
  15. unknown_close_history: 未知页关闭尝试历史,用于超时诊断。
  16. last_enter_success_page_key: 上一次触发进入成功 hook 的页面 key。
  17. """
  18. task_category: str
  19. current_page: Page | None = None
  20. edge_penalties: dict[str, float] = field(default_factory=dict)
  21. local_unknown_closers: list = field(default_factory=list)
  22. pages: dict[str, Page] = field(default_factory=dict)
  23. unknown_close_history: list[str] = field(default_factory=list)
  24. last_enter_success_page_key: str | None = None
  25. def bootstrap(self, pages: list[Page]) -> None:
  26. """使用静态页面定义初始化当前 session。
  27. Args:
  28. pages: 全量静态页面定义列表。
  29. """
  30. self.pages = self._snapshot_pages(pages)
  31. def _snapshot_pages(self, source_pages: list[Page]) -> dict[str, Page]:
  32. """将静态页面定义复制为 session 页面快照。
  33. Args:
  34. source_pages: 静态页面定义列表。
  35. Returns:
  36. 以页面 key 为索引的页面副本字典。
  37. """
  38. cloned_pages = {page.key: page.clone() for page in source_pages}
  39. for page in source_pages:
  40. cloned_page = cloned_pages[page.key]
  41. for transition in page.transitions:
  42. destination = cloned_pages.get(transition.destination.key)
  43. if destination is None:
  44. continue
  45. cloned_page.connect(
  46. destination,
  47. transition.action,
  48. cost=transition.cost,
  49. key=transition.key,
  50. on_enter_success=transition.on_enter_success,
  51. on_enter_failure=transition.on_enter_failure,
  52. on_leave_success=transition.on_leave_success,
  53. on_leave_failure=transition.on_leave_failure,
  54. )
  55. return cloned_pages
  56. def all_pages(self, categories: set[str] = None) -> list[Page]:
  57. """读取当前 session 中允许访问的页面列表。
  58. Args:
  59. categories: 允许返回的页面分类集合;为空时返回全部 session 页面。
  60. Returns:
  61. 页面列表。
  62. """
  63. pages = list(self.pages.values())
  64. if not categories:
  65. return pages
  66. return [page for page in pages if page.category in categories]
  67. def add_page(self, page: Page) -> Page:
  68. """向当前 session 追加一个动态页面。
  69. Args:
  70. page: 页面定义对象。
  71. Returns:
  72. session 内可用的页面副本。
  73. """
  74. current = self.pages.get(page.key)
  75. if current is not None:
  76. return current
  77. cloned_page = page.clone()
  78. self.pages[cloned_page.key] = cloned_page
  79. for transition in page.transitions:
  80. destination = self.resolve_page(transition.destination)
  81. if destination is None:
  82. destination = self.add_page(transition.destination)
  83. cloned_page.connect(
  84. destination,
  85. transition.action,
  86. cost=transition.cost,
  87. key=transition.key,
  88. on_enter_success=transition.on_enter_success,
  89. on_enter_failure=transition.on_enter_failure,
  90. on_leave_success=transition.on_leave_success,
  91. on_leave_failure=transition.on_leave_failure,
  92. )
  93. return cloned_page
  94. def resolve_page(self, page: Page | None) -> Page | None:
  95. """将静态页面定义解析为当前 session 页面副本。
  96. Args:
  97. page: 待解析的页面定义。
  98. Returns:
  99. session 页面对象;无法解析时返回 `None`。
  100. """
  101. if page is None:
  102. return None
  103. current = self.pages.get(page.key)
  104. if current is not None:
  105. return current
  106. registry_page = PageRegistry.get(page.key)
  107. if registry_page is not None:
  108. return self.add_page(registry_page)
  109. return None
  110. def add_unknown_closer(self, *actions) -> None:
  111. """为当前任务追加未知页关闭动作。
  112. Args:
  113. *actions: 额外的关闭动作。
  114. """
  115. self.local_unknown_closers.extend(action for action in actions if action is not None)
  116. def add_penalty(self, transition: Transition, value: float = 1.0) -> float:
  117. """增加一条边的失败惩罚。
  118. Args:
  119. transition: 失败的边。
  120. value: 本次增加的惩罚值。
  121. Returns:
  122. 增加后的总惩罚值。
  123. """
  124. self.edge_penalties[transition.key] = self.edge_penalties.get(transition.key, 0.0) + value
  125. return self.edge_penalties[transition.key]
  126. def penalty_of(self, transition: Transition) -> float:
  127. """读取某条边的当前惩罚值。
  128. Args:
  129. transition: 目标边。
  130. Returns:
  131. 当前惩罚值。
  132. """
  133. return self.edge_penalties.get(transition.key, 0.0)