frontengine 1.0.30__tar.gz → 1.0.31__tar.gz

{frontengine-1.0.30 → frontengine-1.0.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.30
+Version: 1.0.31
 Summary: FrontEngine is use-define frontview or only use like screen saver
 Author-email: JE-Chen <jechenmailman@gmail.com>
 Project-URL: Homepage, https://github.com/Intergration-Automation-Testing/FrontEngine

{frontengine-1.0.30 → frontengine-1.0.31}/frontengine/show/pet/desktop_pet.py

@@ -1,7 +1,9 @@
+import json
 import random as _random_module
 import sys
 from datetime import datetime, timedelta
 from pathlib import Path
+from urllib.parse import urlparse
 from typing import Optional, Tuple
 
 from PySide6.QtCore import Qt, QRect, QTimer, QUrl, Signal
@@ -83,6 +85,10 @@ def scan_pet_pack(folder: str) -> dict:
     return result
 
 
+# 可以請寵物幫忙開啟的網址協定 / URL schemes the pet will open for you
+_WEB_SCHEMES = frozenset({"http", "https"})
+
+
 # 拖進寵物的檔案分類 / What a file dropped onto the pet means
 DROP_SPRITE = "sprite"  # 圖片或動作包 -> 換一套外觀
 DROP_FOOD = "food"      # 其他檔案 -> 當成食物餵給寵物
@@ -142,6 +148,55 @@ def classify_food(path) -> str:
     return FOOD_SNACK
 
 
+# 動作包設定檔：放在動作包資料夾裡，用來描述這隻寵物的個性與參數
+# Pack manifest: sits inside a pet pack folder describing that pet's traits.
+PACK_MANIFEST_NAME = "pet.json"
+_MANIFEST_NUMBERS = ("size", "speed")
+_MANIFEST_FLAGS = ("climb", "talk", "sit_on_windows")
+
+
+def read_pet_manifest(folder) -> dict:
+    """
+    讀取動作包裡的 pet.json（可選）。只取認得的欄位，型別不符就略過，
+    讀不到或格式錯誤一律回傳空 dict，讓動作包永遠不會弄壞寵物。
+
+    Read a pack's optional pet.json. Only known, well-typed fields are kept and
+    anything unreadable yields {}, so a pack can never break the pet.
+    """
+    manifest: dict = {}
+    try:
+        path = Path(folder) / PACK_MANIFEST_NAME
+        if not path.is_file():
+            return manifest
+        with path.open("r", encoding="utf-8") as handle:
+            raw = json.load(handle)
+    except (OSError, ValueError, TypeError):
+        return manifest
+    if not isinstance(raw, dict):
+        return manifest
+    for key in _MANIFEST_NUMBERS:
+        try:
+            if key in raw:
+                manifest[key] = max(1, int(raw[key]))
+        except (TypeError, ValueError):
+            continue
+    for key in _MANIFEST_FLAGS:
+        if isinstance(raw.get(key), bool):
+            manifest[key] = raw[key]
+    if isinstance(raw.get("name"), str):
+        manifest["name"] = raw["name"]
+    if isinstance(raw.get("sound"), str):
+        manifest["sound"] = raw["sound"]
+    lines = raw.get("lines")
+    if isinstance(lines, dict):
+        manifest["lines"] = {
+            str(pool): [str(line) for line in values if str(line).strip()]
+            for pool, values in lines.items()
+            if isinstance(values, list) and values
+        }
+    return manifest
+
+
 def derive_visual_state(dragging: bool, airborne: bool, surface: str, motion_state: str) -> str:
     """依目前情形推導應顯示的視覺狀態 / Derive which sprite state to show."""
     if dragging:
@@ -1101,9 +1156,21 @@ class DesktopPetWidget(BaseWidget):
         self._hunger = PetHunger(user_setting_dict.get("pet_hunger", 70))
         self._hunger_warned = False
         self._messages = self._load_messages()
+        # 動作包自帶的設定（可含台詞、速度、體型、音效）
+        # Traits shipped inside the pack (lines, speed, size, sound).
+        self.manifest = read_pet_manifest(self.image_path) if self.image_path.is_dir() else {}
+        self._apply_manifest()
         self._volume = max(0.0, min(1.0, float(volume)))
         self._sound: Optional[QSoundEffect] = None
-        self._init_sound(sound_path)
+        self._init_sound(self.manifest.get("sound_path", sound_path))
+        # 語音朗讀（可選，缺少 QtTextToSpeech 時自動停用）
+        # Optional spoken lines; disabled automatically without QtTextToSpeech.
+        self._speech = None
+        self._speak = False
+        # AI 對話（可選，需環境變數金鑰；預設關閉）
+        # Optional AI chat; needs an env-var key and is off by default.
+        self._chat_service = None
+        self._pending_chat_reply: Optional[str] = None
         self._sit_on_windows = bool(sit_on_windows)
         self._platform_tick = 0
         # 音訊視覺化：依可注入的音量 provider 脈動 / Audio-reactive pulse
@@ -1152,6 +1219,11 @@ class DesktopPetWidget(BaseWidget):
             language_wrapper.language_word_dict.get("pet_set_reminder", "Set reminder..."), self)
         self.reminder_action.triggered.connect(self._prompt_reminder)
         self.menu.addAction(self.reminder_action)
+        self.chat_action = QAction(
+            language_wrapper.language_word_dict.get("pet_chat_menu", "Talk to me..."), self)
+        self.chat_action.triggered.connect(self._prompt_chat)
+        self.chat_action.setVisible(False)  # shown only when a chat service is attached
+        self.menu.addAction(self.chat_action)
         self.close_action = QAction(language_wrapper.language_word_dict.get("control_center_close_all", "Close"), self)
         self.close_action.triggered.connect(self.close)
         self.menu.addAction(self.close_action)
@@ -1358,6 +1430,58 @@ class DesktopPetWidget(BaseWidget):
         if self._timeline_start is None:
             self._timeline_start = self._now_provider()
 
+    def _apply_manifest(self) -> None:
+        """套用動作包設定：台詞併入句庫，速度／體型／音效覆寫預設值。"""
+        if not self.manifest:
+            return
+        front_engine_logger.info(f"[DesktopPetWidget] pack manifest | {self.manifest}")
+        for pool, lines in (self.manifest.get("lines") or {}).items():
+            self._messages[pool] = list(lines)
+        if "speed" in self.manifest:
+            self.motion.speed = max(1, int(self.manifest["speed"]))
+        if "size" in self.manifest:
+            self._base_size = max(16, int(self.manifest["size"]))
+            self._apply_growth_size()
+        if "climb" in self.manifest:
+            self.motion.climb = bool(self.manifest["climb"])
+        if "talk" in self.manifest:
+            self._talk = bool(self.manifest["talk"])
+        sound = self.manifest.get("sound")
+        if sound:
+            candidate = self.image_path / sound
+            if candidate.is_file():
+                self.manifest["sound_path"] = str(candidate)
+
+    def set_speech_enabled(self, enabled: bool) -> bool:
+        """
+        開關語音朗讀；系統缺少 QtTextToSpeech 時回傳 False 並維持關閉。
+        Toggle spoken lines, returning False when QtTextToSpeech is unavailable.
+        """
+        if not enabled:
+            self._speak = False
+            return False
+        if self._speech is None:
+            try:
+                from PySide6.QtTextToSpeech import QTextToSpeech
+
+                self._speech = QTextToSpeech(self)
+            except Exception as error:  # pragma: no cover - optional Qt module
+                front_engine_logger.warning(f"[DesktopPetWidget] speech unavailable: {error!r}")
+                self._speech = None
+                self._speak = False
+                return False
+        self._speak = True
+        return True
+
+    def _speak_text(self, text: str) -> None:
+        """把台詞念出來（未啟用或失敗時安靜略過）。"""
+        if not self._speak or self._speech is None or not text:
+            return
+        try:
+            self._speech.say(text)
+        except Exception as error:  # pragma: no cover - speech backend guard
+            front_engine_logger.warning(f"[DesktopPetWidget] speech failed: {error!r}")
+
     def _load_messages(self) -> dict:
         d = language_wrapper.language_word_dict
 
@@ -1382,6 +1506,11 @@ class DesktopPetWidget(BaseWidget):
             "away": lines("pet_chatter_away", "Still there?|I'll nap till you're back~|Zzz..."),
             "levelup": lines("pet_chatter_levelup", "Level up!|I'm growing!|We're getting closer!"),
             "costume": lines("pet_chatter_costume", "New look!|How do I look?|Nice fit!"),
+            "fetch": lines("pet_chatter_fetch", "Fetch!|On it!|Opening that for you!"),
+            "focus_start": lines("pet_chatter_focus_start", "Focus time!|Let's concentrate!|I'll wait here."),
+            "focus_break": lines("pet_chatter_focus_break", "Break time!|Stretch a little!|Rest your eyes."),
+            "focus_back": lines("pet_chatter_focus_back", "Back to it!|Round two!|Let's keep going."),
+            "focus_done": lines("pet_chatter_focus_done", "Long break earned!|Great run!|Take a proper rest."),
             "tag": lines("pet_chatter_tag", "You're it!|Caught you!|My turn to chase!"),
             "any": lines("pet_chatter_any", "Hi there!|(^_^)|Keep going!"),
         }
@@ -1489,6 +1618,53 @@ class DesktopPetWidget(BaseWidget):
             return
         self.add_reminder(text.strip(), minutes)
 
+    # --- optional AI chat --------------------------------------------------
+    def set_chat_service(self, service) -> None:
+        """
+        接上 AI 對話服務（None 表示關閉）；服務不可用時右鍵選單不會出現該項目。
+        Attach the AI chat service (None disables it); the menu entry only
+        appears when the service is actually usable.
+        """
+        self._chat_service = service
+        usable = service is not None and bool(getattr(service, "available", lambda: False)())
+        self.chat_action.setVisible(usable)
+
+    def _prompt_chat(self) -> None:
+        """問使用者要說什麼，然後在背景等回覆（不卡 UI）。"""
+        from PySide6.QtWidgets import QInputDialog
+
+        if self._chat_service is None:
+            return
+        title = language_wrapper.language_word_dict.get("pet_chat_menu", "Talk to me...")
+        text, ok = QInputDialog.getText(
+            self, title, language_wrapper.language_word_dict.get("pet_chat_prompt", "Say something:"))
+        if not ok or not text.strip():
+            return
+        self.ask_chat(text.strip())
+
+    def ask_chat(self, message: str) -> None:
+        """送出一句話並在收到回覆時說出來；失敗則說一句抱歉。"""
+        if self._chat_service is None:
+            return
+        self.say(language_wrapper.language_word_dict.get("pet_chat_thinking", "Hmm, let me think..."))
+        self._chat_service.ask_async(message, self.handle_chat_reply)
+
+    def handle_chat_reply(self, reply: Optional[str]) -> None:
+        """處理回覆（可能來自背景執行緒）；空回覆時說一句抱歉。"""
+        if reply:
+            self._pending_chat_reply = reply
+        else:
+            self._pending_chat_reply = language_wrapper.language_word_dict.get(
+                "pet_chat_failed", "I couldn't reach my thoughts just now.")
+        # 回覆可能在背景執行緒抵達，透過計時器回到 UI 執行緒再顯示
+        # The reply may arrive off-thread; hop back to the UI thread to show it.
+        QTimer.singleShot(0, self._say_pending_chat_reply)
+
+    def _say_pending_chat_reply(self) -> None:
+        if self._pending_chat_reply:
+            self.say(self._pending_chat_reply)
+            self._pending_chat_reply = None
+
     def _init_sound(self, sound_path: Optional[str]) -> None:
         if not sound_path:
             return
@@ -1612,6 +1788,7 @@ class DesktopPetWidget(BaseWidget):
             text = pick_message(datetime.now().hour, self._chatter_rng, self._messages, mood=mood)
         if text:
             self._bubble.show_message(text, self)
+            self._speak_text(text)
 
     def _on_tick(self) -> None:
         if self._dragging:
@@ -1688,26 +1865,72 @@ class DesktopPetWidget(BaseWidget):
                 return local_path
         return None
 
+    @staticmethod
+    def dropped_link(mime_data) -> Optional[str]:
+        """
+        從拖曳資料取出網址（拖連結到寵物身上請牠幫忙開啟）；沒有則回傳 None。
+        Pull an http(s) link out of a drop so the pet can open it for you.
+        """
+        if mime_data is None:
+            return None
+        candidates = []
+        if mime_data.hasUrls():
+            candidates += [url.toString() for url in mime_data.urls() if not url.isLocalFile()]
+        if mime_data.hasText():
+            candidates.append(mime_data.text())
+        for candidate in candidates:
+            text = str(candidate or "").strip()
+            # 用網址解析判斷通訊協定，比字串開頭比對穩，也不必在程式碼裡寫死協定前綴。
+            # Parse the URL instead of prefix-matching: sturdier, and no scheme
+            # literals baked into the source.
+            try:
+                scheme = urlparse(text).scheme.lower()
+            except ValueError:
+                continue
+            if scheme in _WEB_SCHEMES:
+                return text
+        return None
+
+    def _accepts_drop(self, mime_data) -> bool:
+        return self.dropped_path(mime_data) is not None or self.dropped_link(mime_data) is not None
+
     def dragEnterEvent(self, event) -> None:
-        if self.dropped_path(event.mimeData()) is not None:
+        if self._accepts_drop(event.mimeData()):
             event.acceptProposedAction()
 
     def dragMoveEvent(self, event) -> None:
-        if self.dropped_path(event.mimeData()) is not None:
+        if self._accepts_drop(event.mimeData()):
             event.acceptProposedAction()
 
     def dropEvent(self, event) -> None:
         path = self.dropped_path(event.mimeData())
-        if path is None:
+        link = self.dropped_link(event.mimeData()) if path is None else None
+        if path is None and link is None:
             return
-        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}")
+        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}, link={link}")
         self.motion.wake()
-        if classify_drop(path) == DROP_SPRITE:
+        if link is not None:
+            self.fetch_link(link)
+        elif classify_drop(path) == DROP_SPRITE:
             self.change_sprite(path)
         else:
             self.feed(classify_food(path))
         event.acceptProposedAction()
 
+    def fetch_link(self, url: str) -> None:
+        """把拖進來的連結叼去瀏覽器開啟，並說一句 / Fetch a dropped link in the browser."""
+        from frontengine.utils.browser.browser import open_browser
+
+        front_engine_logger.info(f"[DesktopPetWidget] fetch_link | url={url}")
+        self._gain_affection(1)
+        pool = self._messages.get("fetch") or []
+        if pool:
+            self.say(pool[self._chatter_rng.randrange(len(pool))])
+        try:
+            open_browser(url)
+        except Exception as error:  # pragma: no cover - browser boundary
+            front_engine_logger.warning(f"[DesktopPetWidget] open_browser failed: {error!r}")
+
     def contextMenuEvent(self, event) -> None:
         self.menu.popup(event.globalPos())
 

{frontengine-1.0.30 → frontengine-1.0.31}/frontengine/ui/page/pet/pet_setting_ui.py

@@ -19,6 +19,10 @@ from frontengine.ui.page.utils import (
 )
 from frontengine.user_setting.user_setting_file import add_recent_file
 from frontengine.utils.audio_meter.screen_audio import audio_level_provider_for_screen
+from frontengine.utils.pet_chat.pet_chat_service import PetChatService
+from frontengine.utils.focus_timer.focus_timer import (
+    PHASE_BREAK, PHASE_FOCUS, PHASE_LONG_BREAK, FocusTimer,
+)
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 
@@ -42,6 +46,14 @@ class PetSettingUI(QWidget):
         self.tag_game = PetTagGame()
         self.tag_timer = QTimer(self)
         self.tag_timer.timeout.connect(self._tick_tag_game)
+        # 專注計時：寵物在每個階段開始時說一句，並在旁邊陪著
+        # Focus timer: the pet announces each phase and keeps you company.
+        self.focus_timer = FocusTimer()
+        self.focus_tick_timer = QTimer(self)
+        self.focus_tick_timer.timeout.connect(self._tick_focus_timer)
+        # AI 對話服務（懶建立，沒有金鑰就自動不可用）
+        # Lazily built chat service; reports itself unavailable without a key.
+        self._chat_service = None
 
         # Choose file
         self.choose_file_button = QPushButton(
@@ -90,6 +102,27 @@ class PetSettingUI(QWidget):
         self.tag_checkbox = QCheckBox(
             language_wrapper.language_word_dict.get("pet_tag_label", "Play tag with each other"))
         self.tag_checkbox.toggled.connect(self._on_tag_toggled)
+        self.speech_checkbox = QCheckBox(
+            language_wrapper.language_word_dict.get("pet_speech_label", "Speak out loud"))
+        self.chat_checkbox = QCheckBox(
+            language_wrapper.language_word_dict.get("pet_chat_label", "AI chat (needs API key)"))
+        self.chat_checkbox.setToolTip(
+            language_wrapper.language_word_dict.get(
+                "pet_chat_hint",
+                "Reads the ANTHROPIC_API_KEY environment variable; the key is never stored."))
+
+        # Focus timer (pomodoro) controls
+        self.focus_label = QLabel(
+            language_wrapper.language_word_dict.get("pet_focus_label", "Focus timer (min)"))
+        self.focus_minutes_combobox = QComboBox()
+        self.focus_minutes_combobox.addItems(["15", "20", "25", "30", "45", "50"])
+        self.focus_minutes_combobox.setCurrentText("25")
+        self.break_minutes_combobox = QComboBox()
+        self.break_minutes_combobox.addItems(["3", "5", "10", "15"])
+        self.break_minutes_combobox.setCurrentText("5")
+        self.focus_button = QPushButton(
+            language_wrapper.language_word_dict.get("pet_focus_start", "Start focus"))
+        self.focus_button.clicked.connect(self.toggle_focus_session)
 
         # Target monitor + sound volume
         self.target_monitor_label = QLabel(
@@ -144,7 +177,13 @@ class PetSettingUI(QWidget):
         self.grid_layout.addWidget(self.volume_combobox, 7, 2)
         self.grid_layout.addWidget(self.audio_react_checkbox, 7, 0)
         self.grid_layout.addWidget(self.tag_checkbox, 7, 1)
-        self.grid_layout.addWidget(self.drop_hint_label, 8, 0, 1, 3)
+        self.grid_layout.addWidget(self.speech_checkbox, 7, 2)
+        self.grid_layout.addWidget(self.focus_label, 8, 0)
+        self.grid_layout.addWidget(self.focus_minutes_combobox, 8, 1)
+        self.grid_layout.addWidget(self.break_minutes_combobox, 8, 2)
+        self.grid_layout.addWidget(self.focus_button, 9, 0)
+        self.grid_layout.addWidget(self.chat_checkbox, 9, 1)
+        self.grid_layout.addWidget(self.drop_hint_label, 10, 0, 1, 3)
 
     def _spawn_pet(self) -> None:
         """建立、顯示並開始移動一隻寵物（供 Start 與右鍵複製共用）。"""
@@ -164,6 +203,10 @@ class PetSettingUI(QWidget):
         )
         pet.clone_requested.connect(self._spawn_pet)
         pet.set_peers_provider(lambda me=pet: self._peer_centers(me))
+        if self.speech_checkbox.isChecked():
+            pet.set_speech_enabled(True)
+        if self.chat_checkbox.isChecked():
+            pet.set_chat_service(self.chat_service())
         geometry = self._target_geometry()
         if self.audio_react_checkbox.isChecked():
             # 跟隨寵物所在螢幕的音源（比對不到就用系統預設輸出裝置）
@@ -179,6 +222,63 @@ class PetSettingUI(QWidget):
             bounds = geometry[0]
             pet.start_moving((bounds.left(), bounds.top(), bounds.right(), bounds.bottom()))
 
+    def chat_service(self) -> PetChatService:
+        """共用的 AI 對話服務（懶建立；沒有金鑰時它自己會回報不可用）。"""
+        if self._chat_service is None:
+            self._chat_service = PetChatService()
+        return self._chat_service
+
+    # --- focus timer -----------------------------------------------------
+    FOCUS_TICK_MS = 1000
+
+    def toggle_focus_session(self) -> None:
+        """開始或停止一次專注（沒有寵物時仍可計時，只是沒人陪你）。"""
+        if self.focus_timer.running:
+            self.stop_focus_session()
+        else:
+            self.start_focus_session()
+
+    def start_focus_session(self) -> None:
+        """依目前設定開始專注，並讓寵物宣布 / Start focusing; the pet announces it."""
+        self.focus_timer.focus_minutes = int(self.focus_minutes_combobox.currentText())
+        self.focus_timer.break_minutes = int(self.break_minutes_combobox.currentText())
+        self.focus_timer.start()
+        front_engine_logger.info(
+            f"[PetSettingUI] focus started | focus={self.focus_timer.focus_minutes}, "
+            f"break={self.focus_timer.break_minutes}"
+        )
+        self.focus_tick_timer.start(self.FOCUS_TICK_MS)
+        self._announce_focus("focus_start")
+        self.focus_button.setText(
+            language_wrapper.language_word_dict.get("pet_focus_stop", "Stop focus"))
+
+    def stop_focus_session(self) -> None:
+        """停止專注 / Stop the focus session."""
+        front_engine_logger.info("[PetSettingUI] focus stopped")
+        self.focus_timer.stop()
+        self.focus_tick_timer.stop()
+        self.focus_button.setText(
+            language_wrapper.language_word_dict.get("pet_focus_start", "Start focus"))
+
+    def _tick_focus_timer(self) -> None:
+        """每秒推進一次；換階段時讓寵物說話。"""
+        phase = self.focus_timer.tick()
+        if phase is None:
+            return
+        if phase == PHASE_FOCUS:
+            self._announce_focus("focus_back")
+        elif phase == PHASE_BREAK:
+            self._announce_focus("focus_break")
+        elif phase == PHASE_LONG_BREAK:
+            self._announce_focus("focus_done")
+
+    def _announce_focus(self, pool_name: str) -> None:
+        """讓所有寵物說出該階段的台詞（沒有寵物就安靜略過）。"""
+        for pet in self._alive_pets():
+            pool = pet._messages.get(pool_name) or []
+            if pool:
+                pet.say(pool[0])
+
     def _target_geometry(self):
         """回傳 (available_geometry, screen) 依所選目標螢幕，否則主螢幕。"""
         screens = QGuiApplication.screens()
@@ -325,6 +425,10 @@ class PetSettingUI(QWidget):
             "volume": self.volume_combobox.currentText(),
             "audio_react": self.audio_react_checkbox.isChecked(),
             "tag": self.tag_checkbox.isChecked(),
+            "speech": self.speech_checkbox.isChecked(),
+            "chat": self.chat_checkbox.isChecked(),
+            "focus_minutes": self.focus_minutes_combobox.currentText(),
+            "break_minutes": self.break_minutes_combobox.currentText(),
         }
 
     def set_state(self, state: dict) -> None:
@@ -364,3 +468,13 @@ class PetSettingUI(QWidget):
             self.audio_react_checkbox.setChecked(bool(state["audio_react"]))
         if "tag" in state:
             self.tag_checkbox.setChecked(bool(state["tag"]))
+        if "speech" in state:
+            self.speech_checkbox.setChecked(bool(state["speech"]))
+        if "chat" in state:
+            self.chat_checkbox.setChecked(bool(state["chat"]))
+        for combobox, key in ((self.focus_minutes_combobox, "focus_minutes"),
+                              (self.break_minutes_combobox, "break_minutes")):
+            if state.get(key) is not None:
+                index = combobox.findText(str(state[key]))
+                if index >= 0:
+                    combobox.setCurrentIndex(index)

frontengine-1.0.31/frontengine/utils/focus_timer/focus_timer.py

@@ -0,0 +1,112 @@
+"""
+番茄鐘／專注計時的純狀態機：專注 -> 休息 -> 專注…，每完成幾輪給一次長休息。
+時間由注入的 now_provider 提供，因此完全可測試、不依賴 Qt。
+
+A pure focus-timer (pomodoro) state machine: focus -> break -> focus…, with a
+long break every few rounds. Time comes from an injected `now_provider`, so it
+is fully testable and Qt-free.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Callable, Optional
+
+PHASE_IDLE = "idle"
+PHASE_FOCUS = "focus"
+PHASE_BREAK = "break"
+PHASE_LONG_BREAK = "long_break"
+
+PHASES = (PHASE_IDLE, PHASE_FOCUS, PHASE_BREAK, PHASE_LONG_BREAK)
+
+
+def clamp_minutes(value, fallback: int, minimum: int = 1, maximum: int = 180) -> int:
+    """把分鐘數夾到合理範圍；無法解析時用 fallback。"""
+    try:
+        return max(minimum, min(maximum, int(float(value))))
+    except (TypeError, ValueError):
+        return fallback
+
+
+class FocusTimer:
+    """
+    專注計時器：start() 進入專注，tick() 在時間到時自動換到下一個階段並回傳新階段
+    （沒換階段回傳 None）。完成 rounds 輪專注後給一次長休息。
+
+    Focus timer: start() begins a focus phase; tick() advances to the next phase
+    when the current one runs out and returns the new phase (None when nothing
+    changed). A long break follows every `rounds` focus phases.
+    """
+
+    def __init__(self, focus_minutes: int = 25, break_minutes: int = 5,
+                 long_break_minutes: int = 15, rounds: int = 4,
+                 now_provider: Callable[[], datetime] = datetime.now) -> None:
+        self.focus_minutes = clamp_minutes(focus_minutes, 25)
+        self.break_minutes = clamp_minutes(break_minutes, 5)
+        self.long_break_minutes = clamp_minutes(long_break_minutes, 15)
+        try:
+            self.rounds = max(1, int(rounds))
+        except (TypeError, ValueError):
+            self.rounds = 4
+        self._now = now_provider
+        self.phase = PHASE_IDLE
+        self.completed_focus = 0
+        self._phase_ends: Optional[datetime] = None
+
+    @property
+    def running(self) -> bool:
+        return self.phase != PHASE_IDLE
+
+    def phase_minutes(self, phase: str) -> int:
+        """該階段的長度（分鐘）。"""
+        if phase == PHASE_FOCUS:
+            return self.focus_minutes
+        if phase == PHASE_BREAK:
+            return self.break_minutes
+        if phase == PHASE_LONG_BREAK:
+            return self.long_break_minutes
+        return 0
+
+    def start(self) -> str:
+        """開始一次專注（重設輪數）/ Begin a focus phase, resetting the round count."""
+        self.completed_focus = 0
+        self._enter(PHASE_FOCUS)
+        return self.phase
+
+    def stop(self) -> None:
+        """停止計時，回到閒置 / Stop and go back to idle."""
+        self.phase = PHASE_IDLE
+        self._phase_ends = None
+
+    def _enter(self, phase: str) -> None:
+        self.phase = phase
+        minutes = self.phase_minutes(phase)
+        self._phase_ends = self._now() + timedelta(minutes=minutes) if minutes else None
+
+    def remaining_seconds(self) -> float:
+        """本階段剩餘秒數；閒置時為 0。"""
+        if self._phase_ends is None:
+            return 0.0
+        return max(0.0, (self._phase_ends - self._now()).total_seconds())
+
+    def next_phase(self) -> str:
+        """算出目前階段結束後應該進入哪個階段（不改變狀態）。"""
+        if self.phase != PHASE_FOCUS:
+            return PHASE_FOCUS
+        if (self.completed_focus + 1) % self.rounds == 0:
+            return PHASE_LONG_BREAK
+        return PHASE_BREAK
+
+    def tick(self) -> Optional[str]:
+        """
+        推進計時：時間未到回傳 None，時間到則切換到下一階段並回傳其名稱。
+        Advance the timer, returning the new phase when one just ended.
+        """
+        if not self.running or self._phase_ends is None:
+            return None
+        if self._now() < self._phase_ends:
+            return None
+        upcoming = self.next_phase()
+        if self.phase == PHASE_FOCUS:
+            self.completed_focus += 1
+        self._enter(upcoming)
+        return upcoming

{frontengine-1.0.30 → frontengine-1.0.31}/frontengine/utils/multi_language/english.py

@@ -271,6 +271,21 @@ english_word_dict = {
     "pet_chatter_fed_hard": "Too hard to chew!|Ouch, my teeth!|That is not food!|Yuck (>_<)",
     "pet_chatter_away": "Still there?|I'll nap till you're back~|Zzz...|Take your time!",
     "pet_chatter_levelup": "Level up!|I'm growing!|We're getting closer!|Yay, thank you!",
+    "pet_speech_label": "Speak out loud",
+    "pet_focus_label": "Focus timer (min)",
+    "pet_focus_start": "Start focus",
+    "pet_focus_stop": "Stop focus",
+    "pet_chatter_fetch": "Fetch!|On it!|Opening that for you!|Leave it to me!",
+    "pet_chatter_focus_start": "Focus time!|Let's concentrate!|I'll wait right here.|You've got this!",
+    "pet_chatter_focus_break": "Break time!|Stretch a little!|Rest your eyes.|Water break?",
+    "pet_chatter_focus_back": "Back to it!|Round two!|Let's keep going.|Ready when you are.",
+    "pet_chatter_focus_done": "Long break earned!|Great run!|Take a proper rest.|Well done!",
+    "pet_chat_label": "AI chat (needs API key)",
+    "pet_chat_hint": "Reads the ANTHROPIC_API_KEY environment variable; the key is never stored.",
+    "pet_chat_menu": "Talk to me...",
+    "pet_chat_prompt": "Say something:",
+    "pet_chat_thinking": "Hmm, let me think...",
+    "pet_chat_failed": "I couldn't reach my thoughts just now.",
     "pet_chatter_costume": "New look!|How do I look?|Nice fit!|I like this one!",
     "pet_chatter_tag": "You're it!|Caught you!|My turn to chase!|Hey, no fair!",
     "pet_tag_label": "Play tag with each other",

{frontengine-1.0.30 → frontengine-1.0.31}/frontengine/utils/multi_language/traditional_chinese.py

@@ -272,6 +272,21 @@ traditional_chinese_word_dict = {
     "pet_chatter_fed_hard": "太硬了咬不動！|我的牙齒啊！|這不是食物吧！|嘔 (>_<)",
     "pet_chatter_away": "還在嗎？|我先打個盹等你回來～|Zzz…|慢慢來沒關係！",
     "pet_chatter_levelup": "升級了！|我長大了！|我們更親近了！|耶，謝謝你！",
+    "pet_speech_label": "把台詞念出來",
+    "pet_focus_label": "專注計時（分鐘）",
+    "pet_focus_start": "開始專注",
+    "pet_focus_stop": "停止專注",
+    "pet_chatter_fetch": "我去開！|交給我！|馬上幫你打開！|收到！",
+    "pet_chatter_focus_start": "專注時間到！|一起集中精神！|我在旁邊陪你。|你可以的！",
+    "pet_chatter_focus_break": "休息一下！|起來動一動！|讓眼睛休息。|喝點水吧？",
+    "pet_chatter_focus_back": "回到工作囉！|第二回合！|繼續加油。|準備好就開始。",
+    "pet_chatter_focus_done": "可以放長假囉！|這輪很棒！|好好休息一下。|辛苦了！",
+    "pet_chat_label": "AI 對話（需要 API 金鑰）",
+    "pet_chat_hint": "讀取環境變數 ANTHROPIC_API_KEY；金鑰不會被儲存。",
+    "pet_chat_menu": "跟我說話…",
+    "pet_chat_prompt": "想說什麼：",
+    "pet_chat_thinking": "嗯…讓我想一下…",
+    "pet_chat_failed": "我現在想不出話來耶。",
     "pet_chatter_costume": "換新裝！|好看嗎？|很合身耶！|我喜歡這套！",
     "pet_chatter_tag": "換你當鬼！|抓到你了！|輪到我追了！|喂，不公平啦！",
     "pet_tag_label": "寵物玩鬼抓人",