je-editor 0.0.223__py3-none-any.whl → 0.0.224__py3-none-any.whl

je_editor/pyside_ui/main_ui/ai_widget/langchain_interface.py

@@ -14,24 +14,59 @@ from je_editor.utils.multi_language.multi_language_wrapper import language_wrapp
 if TYPE_CHECKING:
     from je_editor.pyside_ui.main_ui.ai_widget.chat_ui import ChatUI
 
+
 class LangChainInterface(object):
+    """
+    LangChainInterface 負責與 LangChain + OpenAI 模型互動
+    LangChainInterface is responsible for interacting with LangChain + OpenAI model
+    """
+
+    def __init__(self, main_window: ChatUI, prompt_template: str, base_url: str,
+                 api_key: Union[SecretStr, str], chat_model: str):
+        """
+        初始化 LangChainInterface
+        Initialize LangChainInterface
 
-    def __init__(self, main_window: ChatUI, prompt_template: str, base_url: str, api_key: Union[SecretStr, str],
-                 chat_model: str):
+        :param main_window: 主視窗，用於顯示錯誤訊息 / Main window, used for showing error messages
+        :param prompt_template: 系統提示詞模板 / System prompt template
+        :param base_url: OpenAI API 的基礎 URL / Base URL for OpenAI API
+        :param api_key: OpenAI API 金鑰 / OpenAI API key
+        :param chat_model: 使用的聊天模型名稱 / Chat model name
+        """
+        # 建立系統提示詞模板 / Create system message prompt template
         self.system_message_prompt = SystemMessagePromptTemplate.from_template(prompt_template)
+
+        # 儲存基本設定 / Store basic settings
         self.base_url = base_url
         self.api_key = api_key
         self.chat_model = chat_model
         self.main_window = main_window
+
+        # 將設定寫入環境變數，方便其他套件讀取
+        # Save settings into environment variables for other packages to read
         os.environ["OPENAI_BASE_URL"] = self.base_url
         os.environ["OPENAI_API_KEY"] = self.api_key
         os.environ["CHAT_MODEL"] = self.chat_model
+
+        # 初始化 ChatOpenAI 物件，用於呼叫模型
+        # Initialize ChatOpenAI object for model invocation
         self.chat_ai = ChatOpenAI(base_url=self.base_url, api_key=self.api_key, model=self.chat_model)
 
     def call_ai_model(self, prompt: str) -> str | None:
+        """
+        呼叫 AI 模型並回傳結果
+        Call AI model and return response
+
+        :param prompt: 使用者輸入的提示詞 / User input prompt
+        :return: AI 回覆文字或 None / AI response text or None
+        """
         message = None
         try:
+            # 呼叫 AI 並取得回覆 / Invoke AI and get response
             message = self.chat_ai.invoke(prompt).text()
+
+            # 嘗試過濾掉 <think> 標籤前的內容，只保留主要回覆
+            # Try to filter out content before </think>, keep only main response
             match = re.search(r"</think>\s*(.*)", message, re.DOTALL)
             if match:
                 message = match.group(1).strip()
@@ -39,7 +74,11 @@ class LangChainInterface(object):
                 message = message
 
         except Exception as error:
-            QMessageBox.warning(self.main_window,
-                                language_wrapper.language_word_dict.get("call_ai_model_error_title"),
-                                str(error))
-        return message
+            # 發生錯誤時，彈出警告視窗顯示錯誤訊息
+            # Show error message in a warning dialog if exception occurs
+            QMessageBox.warning(
+                self.main_window,
+                language_wrapper.language_word_dict.get("call_ai_model_error_title"),
+                str(error)
+            )
+        return message

je_editor/pyside_ui/main_ui/console_widget/console_gui.py

@@ -12,42 +12,59 @@ from je_editor.utils.multi_language.multi_language_wrapper import language_wrapp
 
 
 class ConsoleWidget(QWidget):
+    """
+    ConsoleWidget 提供一個互動式終端機介面，讓使用者可以輸入指令並查看輸出。
+    ConsoleWidget provides an interactive console interface for running commands and viewing output.
+    """
+
     def __init__(self, parent=None):
         super().__init__(parent)
         self.language_word_dict_get = language_wrapper.language_word_dict.get
+
+        # 初始化子程序控制器 / Initialize process adapter
         self.proc = ConsoleProcessAdapter(self)
-        self.proc.stdout.connect(self.append_text)
-        self.proc.stderr.connect(lambda t: self.append_text(t, "#d33"))
+        self.proc.stdout.connect(self.append_text)  # 標準輸出 / Standard output
+        self.proc.stderr.connect(lambda t: self.append_text(t, "#d33"))  # 錯誤輸出 (紅色) / Error output (red)
         self.proc.system.connect(
-            lambda t: self.append_text(f"{self.language_word_dict_get('dynamic_console_system_prefix')}{t}\n", "#888"))
+            lambda t: self.append_text(f"{self.language_word_dict_get('dynamic_console_system_prefix')}{t}\n", "#888")
+        )
         self.proc.started.connect(lambda: self.proc.system.emit(self.language_word_dict_get("dynamic_console_running")))
         self.proc.finished.connect(self.on_finished)
 
+        # 指令歷史紀錄 / Command history
         self.history, self.history_index = [], -1
 
+        # 輸出區域 / Output area
         self.output = QPlainTextEdit(readOnly=True)
-        self.output.setMaximumBlockCount(10000)
+        self.output.setMaximumBlockCount(10000)  # 最多保留 10000 行 / Keep up to 10000 lines
         self.output.setStyleSheet("font-family: Consolas, monospace;")
 
+        # 輸入框 / Input field
         self.input = QLineEdit()
-        self.input.setPlaceholderText("Enter command")
-        self.input.returnPressed.connect(self.run_command)
-        self.input.installEventFilter(self)
+        self.input.setPlaceholderText("Enter command")  # 預設提示文字 / Placeholder text
+        self.input.returnPressed.connect(self.run_command)  # 按 Enter 執行指令 / Run command on Enter
+        self.input.installEventFilter(self)  # 安裝事件過濾器，用於上下鍵瀏覽歷史 / Install event filter for history navigation
 
+        # 控制按鈕 / Control buttons
         self.btn_run = QPushButton(self.language_word_dict_get("dynamic_console_run"))
         self.btn_run.clicked.connect(self.run_command)
+
         self.btn_stop = QPushButton(self.language_word_dict_get("dynamic_console_stop"))
         self.btn_stop.clicked.connect(self.proc.stop)
+
         self.btn_clear = QPushButton(self.language_word_dict_get("dynamic_console_clear"))
         self.btn_clear.clicked.connect(self.output.clear)
 
+        # 工作目錄顯示與選擇 / Current working directory display and picker
         self.cwd_label = QLabel(f"{self.language_word_dict_get('dynamic_console_cwd')}: {os.getcwd()}")
         self.btn_pick_cwd = QPushButton("…")
         self.btn_pick_cwd.clicked.connect(self.pick_cwd)
 
+        # Shell 選擇下拉選單 / Shell selection combobox
         self.shell_combo = QComboBox()
         self.shell_combo.addItems(["auto", "cmd", "powershell", "bash", "sh"])
 
+        # 版面配置：上方 (工作目錄 + Shell 選擇) / Layout: Top (CWD + Shell selection)
         top = QHBoxLayout()
         top.addWidget(self.cwd_label)
         top.addWidget(self.btn_pick_cwd)
@@ -55,21 +72,27 @@ class ConsoleWidget(QWidget):
         top.addWidget(QLabel(self.language_word_dict_get("dynamic_console_shell")))
         top.addWidget(self.shell_combo)
 
+        # 版面配置：中間 (輸入框 + 按鈕) / Layout: Middle (Input + Buttons)
         mid = QHBoxLayout()
         mid.addWidget(self.input, 1)
         mid.addWidget(self.btn_run)
         mid.addWidget(self.btn_stop)
         mid.addWidget(self.btn_clear)
 
+        # 主版面配置 / Main layout
         lay = QVBoxLayout(self)
         lay.addLayout(top)
         lay.addWidget(self.output, 1)
         lay.addLayout(mid)
 
+        # 初始化狀態訊息 / Initial status message
         self.proc.system.emit(self.language_word_dict_get("dynamic_console_ready"))
-        # 啟動互動式 shell
+
+        # 啟動互動式 shell / Start interactive shell
         self.proc.start_shell(self.shell_combo.currentText())
 
+    # 事件過濾器：支援上下鍵瀏覽歷史指令
+    # Event filter: Support navigating command history with Up/Down keys
     def eventFilter(self, obj, event):
         if obj is self.input and isinstance(event, QKeyEvent) and event.type() == QEvent.Type.KeyPress:
             if event.key() == Qt.Key.Key_Up:
@@ -80,12 +103,14 @@ class ConsoleWidget(QWidget):
                 return True
         return super().eventFilter(obj, event)
 
+    # 瀏覽上一個歷史指令 / Navigate to previous command in history
     def history_prev(self):
         if not self.history: return
         self.history_index = len(self.history) - 1 if self.history_index < 0 else max(0, self.history_index - 1)
         self.input.setText(self.history[self.history_index])
         self.input.end(False)
 
+    # 瀏覽下一個歷史指令 / Navigate to next command in history
     def history_next(self):
         if not self.history: return
         if self.history_index < 0: return
@@ -97,6 +122,7 @@ class ConsoleWidget(QWidget):
             self.input.setText(self.history[self.history_index])
             self.input.end(False)
 
+    # 選擇新的工作目錄 / Pick a new working directory
     def pick_cwd(self):
         d = QFileDialog.getExistingDirectory(self, "Select working directory", os.getcwd())
         if d:
@@ -104,16 +130,19 @@ class ConsoleWidget(QWidget):
             self.cwd_label.setText(f"{self.language_word_dict_get('dynamic_console_cwd')}: {d}")
             self.proc.system.emit(f'cd "{d}"')
 
+    # 在輸出區域新增文字 (支援顏色) / Append text to output area (with optional color)
     def append_text(self, text, color=None):
         cursor = self.output.textCursor()
         cursor.movePosition(QTextCursor.MoveOperation.End)
         fmt = self.output.currentCharFormat()
-        if color: fmt.setForeground(QColor(color))
+        if color:
+            fmt.setForeground(QColor(color))
         cursor.setCharFormat(fmt)
         cursor.insertText(text)
         self.output.setTextCursor(cursor)
         self.output.ensureCursorVisible()
 
+    # 執行輸入的指令 / Run the entered command
     def run_command(self):
         cmd = self.input.text().strip()
         if not cmd: return
@@ -124,7 +153,10 @@ class ConsoleWidget(QWidget):
         self.proc.send_command(cmd)
         self.input.clear()
 
+    # 子程序結束時的處理 / Handle process finished event
     def on_finished(self, code, status):
-        self.append_text(f"\n{self.language_word_dict_get('dynamic_console_done').format(code=code, status=status)}\n",
-                         "#888")
-        self.proc.system.emit(self.language_word_dict_get("dynamic_console_ready"))
+        self.append_text(
+            f"\n{self.language_word_dict_get('dynamic_console_done').format(code=code, status=status)}\n",
+            "#888"
+        )
+        self.proc.system.emit(self.language_word_dict_get("dynamic_console_ready"))

je_editor/pyside_ui/main_ui/console_widget/qprocess_adapter.py

@@ -4,60 +4,81 @@ from PySide6.QtCore import QObject, QProcess, Signal, QTimer
 
 
 class ConsoleProcessAdapter(QObject):
-    started = Signal()
-    finished = Signal(int, QProcess.ExitStatus)
-    stdout = Signal(str)
-    stderr = Signal(str)
-    system = Signal(str)
+    """
+    ConsoleProcessAdapter 負責管理 QProcess，提供互動式 shell 的啟動、指令傳送與輸出監聽。
+    ConsoleProcessAdapter manages QProcess, providing interactive shell start, command sending, and output handling.
+    """
+
+    # 定義訊號 / Define signals
+    started = Signal()  # 當子程序啟動時發射 / Emitted when process starts
+    finished = Signal(int, QProcess.ExitStatus)  # 當子程序結束時發射 / Emitted when process finishes
+    stdout = Signal(str)  # 標準輸出訊號 / Standard output signal
+    stderr = Signal(str)  # 錯誤輸出訊號 / Standard error signal
+    system = Signal(str)  # 系統訊息訊號 / System message signal
 
     def __init__(self, parent=None):
         super().__init__(parent)
+        # 建立 QProcess 物件 / Create QProcess object
         self.proc = QProcess(self)
+        # 設定輸出通道分離 (stdout / stderr) / Separate stdout and stderr
         self.proc.setProcessChannelMode(QProcess.ProcessChannelMode.SeparateChannels)
+
+        # 綁定事件處理函式 / Connect signals to handlers
         self.proc.readyReadStandardOutput.connect(self._on_stdout)
         self.proc.readyReadStandardError.connect(self._on_stderr)
         self.proc.started.connect(self.started)
         self.proc.finished.connect(self.finished)
 
+    # 設定工作目錄 / Set working directory
     def set_cwd(self, path: str):
         self.proc.setWorkingDirectory(path)
 
+    # 啟動 shell / Start shell
     def start_shell(self, shell: str = "auto"):
         if self.is_running():
-            self.system.emit("Shell already running")
+            self.system.emit("Shell already running")  # 如果已經在執行，發送提示 / Emit message if already running
             return
-        program, args = self._build_shell_command(shell)
-        self.proc.start(program, args)
+        program, args = self._build_shell_command(shell)  # 建立 shell 指令 / Build shell command
+        self.proc.start(program, args)  # 啟動子程序 / Start process
 
+        # Windows 特殊處理：設定 UTF-8 編碼 / Windows-specific: set UTF-8 encoding
         if os.name == "nt":
             QTimer.singleShot(500, lambda: self.send_command("chcp 65001"))
 
+    # 傳送指令到 shell / Send command to shell
     def send_command(self, cmd: str):
         if not self.is_running():
-            self.system.emit("Shell not running")
+            self.system.emit("Shell not running")  # 如果 shell 未啟動，發送提示 / Emit message if not running
             return
-        self.proc.write((cmd + "\n").encode("utf-8"))
+        self.proc.write((cmd + "\n").encode("utf-8"))  # 傳送指令並換行 / Send command with newline
 
+    # 停止 shell / Stop shell
     def stop(self):
         if not self.is_running():
             return
-        self.proc.terminate()
+        self.proc.terminate()  # 嘗試正常結束 / Try graceful termination
+        # 如果 1 秒後仍在執行，強制 kill / Force kill if still running after 1s
         QTimer.singleShot(1000, lambda: self.is_running() and self.proc.kill())
 
+    # 判斷是否正在執行 / Check if process is running
     def is_running(self):
         return self.proc.state() != QProcess.ProcessState.NotRunning
 
+    # 處理標準輸出 / Handle standard output
     def _on_stdout(self):
         self.stdout.emit(bytes(self.proc.readAllStandardOutput()).decode("utf-8", errors="replace"))
 
+    # 處理錯誤輸出 / Handle standard error
     def _on_stderr(self):
         self.stderr.emit(bytes(self.proc.readAllStandardError()).decode("utf-8", errors="replace"))
 
+    # 建立 shell 指令 / Build shell command
     def _build_shell_command(self, shell: str):
         if shell == "auto":
-            shell = "cmd" if os.name == "nt" else "bash"
+            shell = "cmd" if os.name == "nt" else "bash"  # Windows 預設 cmd，Linux/macOS 預設 bash
         if os.name == "nt":
             if shell == "powershell":
                 return "powershell.exe", ["-NoLogo", "-NoProfile", "-ExecutionPolicy", "Bypass"]
             return "cmd.exe", []
-        return ("/bin/bash" if shell == "bash" else "/bin/sh"), []
+        # Linux/macOS 預設 bash，否則使用 sh / Default bash, fallback to sh
+        return ("/bin/bash" if shell == "bash" else "/bin/sh"), []

je_editor/pyside_ui/main_ui/dock/destroy_dock.py

@@ -5,15 +5,46 @@ from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 class DestroyDock(QDockWidget):
+    """
+    DestroyDock 繼承自 QDockWidget，主要用於建立一個可停駐的視窗，
+    並在關閉時自動釋放資源與記錄日誌。
+
+    DestroyDock inherits from QDockWidget, mainly used to create a dockable window,
+    and automatically release resources and log events when closed.
+    """
 
     def __init__(self):
+        # 初始化時記錄日誌 / Log initialization
         jeditor_logger.info("Init DestroyDock")
         super().__init__()
+
+        # 設定允許停駐的區域 (可停駐在所有邊)
+        # Allow docking in all areas (top, bottom, left, right)
         self.setAllowedAreas(Qt.DockWidgetArea.AllDockWidgetAreas)
-        # Attr
+
+        # 設定屬性：當視窗關閉時，自動刪除物件以釋放記憶體
+        # Set attribute: delete object on close to free memory
         self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
 
     def closeEvent(self, event) -> None:
+        """
+        覆寫 closeEvent，在關閉時額外處理：
+        - 記錄關閉事件
+        - 關閉內部 widget
+        - 呼叫父類別的 close()
+
+        Override closeEvent to:
+        - Log the close event
+        - Close the internal widget
+        - Call parent close()
+        """
+        # 記錄關閉事件 / Log close event
         jeditor_logger.info(f"DestroyDock closeEvent event: {event}")
+
+        # 關閉 dock 內部的 widget，確保資源釋放
+        # Close the internal widget to ensure resource release
         self.widget().close()
-        super().close()
+
+        # 呼叫父類別的 close()，完成 Qt 預設的關閉流程
+        # Call parent close() to complete default Qt closing process
+        super().close()

je_editor/pyside_ui/main_ui/editor/editor_widget.py

@@ -32,11 +32,24 @@ from je_editor.utils.file.open.open_file import read_file
 
 
 class EditorWidget(QWidget):
+    """
+    EditorWidget 是主要的程式碼編輯器元件，包含：
+    - 專案檔案樹狀檢視
+    - 程式碼編輯區
+    - 執行結果、格式檢查、除錯輸出
+    - 自動儲存與檔案管理
+
+    EditorWidget is the main code editor widget, including:
+    - Project file tree view
+    - Code editing area
+    - Execution result, format check, debugger output
+    - Auto-save and file management
+    """
 
     def __init__(self, main_window: EditorMain):
         jeditor_logger.info(f"Init EditorWidget main_window: {main_window}")
         super().__init__()
-        # Init variable
+        # ---------------- Init variables 初始化變數 ----------------
         self.checker: Union[PEP8FormatChecker, None] = None
         self.current_file = None
         self.tree_view_scroll_area = None
@@ -45,41 +58,51 @@ class EditorWidget(QWidget):
         self.python_compiler = None
         self.main_window = main_window
         self.tab_manager = self.main_window.tab_widget
-        # Attr
-        # Current execute instance if none not running
+
+        # 執行相關物件 / Execution related objects
         self.exec_program: Union[None, ExecManager] = None
         self.exec_shell: Union[None, ShellManager] = None
         self.exec_python_debugger: Union[None, ExecManager] = None
-        # Autosave
+
+        # 自動儲存執行緒 / Auto-save thread
         self.code_save_thread: Union[CodeEditSaveThread, None] = None
-        # UI
+
+        # ---------------- UI 初始化 ----------------
         self.grid_layout = QGridLayout(self)
         self.setWindowTitle(language_wrapper.language_word_dict.get("application_name"))
-        # Treeview
+
+        # 建立專案檔案樹狀檢視 / Setup project tree view
         self.set_project_treeview()
-        # Use to put full ui
+
+        # 主分割器 (左：檔案樹，右：編輯器) / Main splitter (left: tree, right: editor)
         self.full_splitter = QSplitter()
         self.full_splitter.setOrientation(Qt.Orientation.Horizontal)
-        # Code edit and result QSplitter
+
+        # 編輯器分割器 (上：編輯器，下：輸出) / Editor splitter (top: editor, bottom: output)
         self.edit_splitter = QSplitter(self.full_splitter)
         self.edit_splitter.setOrientation(Qt.Orientation.Vertical)
-        # code edit and code result plaintext
+
+        # 程式碼編輯器與輸出區 / Code editor and result area
         self.code_edit = CodeEditor(self)
         self.code_result = CodeRecord()
         self.code_result_cursor = self.code_result.textCursor()
+
+        # 捲動區包裝編輯器與輸出 / Scroll areas for editor and result
         self.code_edit_scroll_area = QScrollArea()
         self.code_edit_scroll_area.setWidgetResizable(True)
         self.code_edit_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.code_edit_scroll_area.setWidget(self.code_edit)
+
         self.code_result_scroll_area = QScrollArea()
         self.code_result_scroll_area.setWidgetResizable(True)
         self.code_result_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.code_result_scroll_area.setWidget(self.code_result)
-        # Code format checker
+
+        # 格式檢查與除錯輸出 / Format check and debugger output
         self.format_check_result = CodeRecord()
-        # Debugger
         self.debugger_result = CodeRecord()
-        # Code result tab
+
+        # 輸出分頁 (執行結果 / 格式檢查 / 除錯) / Output tabs
         self.code_difference_result = QTabWidget()
         self.code_difference_result.addTab(
             self.code_result_scroll_area, language_wrapper.language_word_dict.get("editor_code_result"))
@@ -87,18 +110,21 @@ class EditorWidget(QWidget):
             self.format_check_result, language_wrapper.language_word_dict.get("editor_format_check"))
         self.code_difference_result.addTab(
             self.debugger_result, language_wrapper.language_word_dict.get("editor_debugger_input_title_label"))
-        # Edit splitter
+
+        # 加入分割器 / Add widgets to splitters
         self.edit_splitter.addWidget(self.code_edit_scroll_area)
         self.edit_splitter.addWidget(self.code_difference_result)
         self.edit_splitter.setStretchFactor(0, 3)
         self.edit_splitter.setStretchFactor(1, 1)
         self.edit_splitter.setSizes([300, 100])
+
         self.full_splitter.addWidget(self.project_treeview)
         self.full_splitter.addWidget(self.edit_splitter)
         self.full_splitter.setStretchFactor(0, 1)
         self.full_splitter.setStretchFactor(1, 3)
         self.full_splitter.setSizes([100, 300])
-        # Font
+
+        # 設定字體樣式 / Set font style
         self.code_edit.setStyleSheet(
             f"font-size: {user_setting_dict.get('font_size', 12)}pt;"
             f"font-family: {user_setting_dict.get('font', 'Lato')};"
@@ -107,15 +133,23 @@ class EditorWidget(QWidget):
             f"font-size: {user_setting_dict.get('font_size', 12)}pt;"
             f"font-family: {user_setting_dict.get('font', 'Lato')};"
         )
-        # Add to layout
+
+        # 加入主版面配置 / Add to main layout
         self.grid_layout.addWidget(self.full_splitter)
 
+    # ---------------- Project Treeview ----------------
     def set_project_treeview(self) -> None:
+        """
+        建立並設定專案檔案樹狀檢視
+        Setup and configure project file tree view
+        """
         jeditor_logger.info("EditorWidget set_project_treeview")
         self.project_treeview_model = QFileSystemModel()
         self.project_treeview_model.setRootPath(QDir.currentPath())
         self.project_treeview = QTreeView()
         self.project_treeview.setModel(self.project_treeview_model)
+
+        # 設定根目錄 (工作目錄或當前路徑) / Set root directory (working dir or current path)
         if self.main_window.working_dir is None:
             self.project_treeview.setRootIndex(
                 self.project_treeview_model.index(str(Path.cwd()))
@@ -124,53 +158,87 @@ class EditorWidget(QWidget):
             self.project_treeview.setRootIndex(
                 self.project_treeview_model.index(self.main_window.working_dir)
             )
+
+        # 包裝成可捲動區域 / Wrap in scroll area
         self.tree_view_scroll_area = QScrollArea()
         self.tree_view_scroll_area.setWidgetResizable(True)
         self.tree_view_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.tree_view_scroll_area.setWidget(self.project_treeview)
         self.grid_layout.addWidget(self.tree_view_scroll_area, 0, 0, 0, 1)
+
+        # 點擊檔案時觸發 / Connect click event
         self.project_treeview.clicked.connect(self.treeview_click)
 
     def check_is_open(self, path: Path):
+        """
+        檢查檔案是否已經開啟，如果已開啟則切換到該分頁。
+        Check if the file is already open, if yes then switch to that tab.
+        """
         jeditor_logger.info(f"EditorWidget check_is_open path: {path}")
         if file_is_open_manager_dict.get(str(path), None) is not None:
+            # 嘗試在分頁中找到對應的 EditorWidget
+            # Try to find the corresponding EditorWidget in tab manager
             widget: QWidget = self.tab_manager.findChild(EditorWidget, str(path))
             if widget is None:
+                # 如果找不到，代表之前的紀錄失效，移除紀錄
+                # If not found, remove stale record
                 file_is_open_manager_dict.pop(str(path), None)
             else:
+                # 如果找到，直接切換到該分頁
+                # If found, switch to that tab
                 self.tab_manager.setCurrentWidget(widget)
                 return False
         else:
+            # 如果檔案未開啟，加入紀錄
+            # If file not open, add to open manager dict
             file_is_open_manager_dict.update({str(path): str(path)})
             return True
 
     def open_an_file(self, path: Path) -> bool:
         """
-        :param path: open file path
-        :return: return False if file tab exists
+        開啟檔案並載入到編輯器。
+        Open a file and load it into the editor.
+
+        :param path: 檔案路徑 / File path
+        :return: 如果檔案已經開啟則回傳 False / Return False if file tab already exists
         """
         jeditor_logger.info(f"EditorWidget open_an_file path: {path}")
         if not self.check_is_open(path):
             return False
+
+        # 如果有自動儲存執行緒，暫時跳過這一輪
+        # If auto-save thread exists, skip this round
         if self.code_save_thread:
             self.code_save_thread.skip_this_round = True
+
+        # 讀取檔案內容 / Read file content
         file, file_content = read_file(str(path))
-        self.code_edit.setPlainText(
-            file_content
-        )
+        self.code_edit.setPlainText(file_content)
+
+        # 更新目前檔案資訊 / Update current file info
         self.current_file = file
         self.code_edit.current_file = file
         self.code_edit.reset_highlighter()
+
+        # 更新使用者設定中的最後開啟檔案 / Update last opened file in user settings
         user_setting_dict.update({"last_file": str(self.current_file)})
+
+        # 啟動或更新自動儲存執行緒 / Start or update auto-save thread
         if self.current_file is not None and self.code_save_thread is None:
             init_new_auto_save_thread(self.current_file, self)
         else:
             self.code_save_thread.file = self.current_file
             self.code_save_thread.skip_this_round = False
+
+        # 更新分頁標籤名稱 / Update tab title
         self.rename_self_tab()
         return True
 
     def treeview_click(self) -> None:
+        """
+        當使用者點擊檔案樹中的項目時觸發。
+        Triggered when user clicks an item in the project tree view.
+        """
         jeditor_logger.info("EditorWidget treeview_click")
         clicked_item: QFileSystemModel = self.project_treeview.selectedIndexes()[0]
         file_info: QFileInfo = self.project_treeview.model().fileInfo(clicked_item)
@@ -179,6 +247,10 @@ class EditorWidget(QWidget):
             self.open_an_file(path)
 
     def rename_self_tab(self):
+        """
+        將目前分頁的標籤名稱改為目前檔案名稱。
+        Rename the current tab to the current file name.
+        """
         jeditor_logger.info("EditorWidget rename_self_tab")
         if self.tab_manager.currentWidget() is self:
             self.tab_manager.setTabText(
@@ -186,13 +258,20 @@ class EditorWidget(QWidget):
             self.setObjectName(str(Path(self.current_file)))
 
     def check_file_format(self):
+        """
+        檢查目前檔案的程式碼格式 (僅支援 Python)。
+        Check the code format of the current file (only supports Python).
+        """
         if self.current_file:
             jeditor_logger.info("EditorWidget check_file_format")
             suffix_checker = Path(self.current_file).suffix
             if suffix_checker == ".py":
+                # 使用 PEP8 格式檢查器 / Use PEP8 format checker
                 self.checker = PEP8FormatChecker(self.current_file)
                 self.checker.check_all_format()
                 self.format_check_result.setPlainText("")
+
+                # 顯示錯誤訊息並套用顏色 / Display errors with color formatting
                 for error in self.checker.error_list:
                     text_cursor = self.format_check_result.textCursor()
                     text_format = QTextCharFormat()
@@ -201,12 +280,17 @@ class EditorWidget(QWidget):
                     text_cursor.insertBlock()
                 self.checker.error_list.clear()
             else:
+                # 非 Python 檔案，顯示提示訊息 / Show message if not Python file
                 message_box = QMessageBox()
                 message_box.setText(
                     language_wrapper.language_word_dict.get("python_format_checker_only_support_python_message"))
                 message_box.exec_()
 
     def close(self) -> bool:
+        """
+        關閉編輯器，釋放資源並移除自動儲存紀錄。
+        Close the editor, release resources, and remove auto-save records.
+        """
         jeditor_logger.info("EditorWidget close")
         if self.code_save_thread is not None:
             self.code_save_thread.still_run = False