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

je_editor/pyside_ui/main_ui/ai_widget/ai_config.py

@@ -2,18 +2,33 @@ from queue import Queue
 
 
 class AIConfig(object):
+    """
+    AIConfig 類別：用來管理 AI 模型的設定與訊息佇列
+    AIConfig class: manages AI model configuration and message queue
+    """
 
     def __init__(self):
+        # 當前 AI 模型的系統提示詞 (system prompt)
+        # Current AI model system prompt
         self.current_ai_model_system_prompt: str = ""
+
+        # 可選擇的 AI 模型設定字典
+        # Dictionary of choosable AI model configurations
+        # 結構: { "AI_model": { "ai_base_url": ..., "ai_api_key": ..., "chat_model": ..., "prompt_template": ... } }
         self.choosable_ai: dict[str, dict[str, str]] = {
             "AI_model": {
-                "ai_base_url": "",
-                "ai_api_key": "",
-                "chat_model": "",
-                "prompt_template": "",
+                "ai_base_url": "",       # AI 服務的基礎 URL / Base URL of AI service
+                "ai_api_key": "",        # API 金鑰 / API key
+                "chat_model": "",        # 模型名稱 / Model name
+                "prompt_template": "",   # 提示詞模板 / Prompt template
             }
         }
+
+        # 訊息佇列，用來暫存與 AI 的互動訊息
+        # Message queue for storing AI interaction messages
         self.message_queue = Queue()
 
 
-ai_config = AIConfig()
+# 建立全域唯一的 AIConfig 實例
+# Create a global singleton instance of AIConfig
+ai_config = AIConfig()

je_editor/pyside_ui/main_ui/ai_widget/ask_thread.py

@@ -5,13 +5,32 @@ from je_editor.pyside_ui.main_ui.ai_widget.langchain_interface import LangChainI
 
 
 class AskThread(Thread):
+    """
+    AskThread 類別：用來在背景執行緒中呼叫 AI 模型，避免阻塞主執行緒
+    AskThread class: runs AI model calls in a background thread to avoid blocking the main thread
+    """
 
     def __init__(self, lang_chain_interface: LangChainInterface, prompt):
+        """
+        初始化 AskThread
+        Initialize AskThread
+        :param lang_chain_interface: LangChainInterface 實例，用來呼叫 AI 模型
+                                     LangChainInterface instance for calling AI model
+        :param prompt: 傳給 AI 模型的提示詞
+                       Prompt to send to the AI model
+        """
         super().__init__()
         self.lang_chain_interface = lang_chain_interface
         self.prompt = prompt
 
-
     def run(self):
+        """
+        執行緒的主要邏輯：
+        1. 呼叫 AI 模型並取得回應
+        2. 將回應放入 ai_config 的 message_queue 中，供主程式使用
+        Thread main logic:
+        1. Call AI model and get response
+        2. Put response into ai_config.message_queue for main program to consume
+        """
         ai_response = self.lang_chain_interface.call_ai_model(prompt=self.prompt)
         ai_config.message_queue.put(ai_response)

je_editor/pyside_ui/main_ui/ai_widget/chat_ui.py

@@ -23,73 +23,86 @@ class ChatUI(QWidget):
 
     def __init__(self, main_window: EditorMain):
         super().__init__()
-        self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+        self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)  # 關閉視窗時自動釋放資源 / Auto delete on close
         self.main_window = main_window
-        # Chat panel
-        self.chat_panel = QPlainTextEdit()
-        self.chat_panel.setLineWrapMode(self.chat_panel.LineWrapMode.NoWrap)
-        self.chat_panel.setReadOnly(True)
-        self.chat_panel_scroll_area = QScrollArea()
+
+        # ---------------- Chat Panel 聊天面板 ----------------
+        self.chat_panel = QPlainTextEdit()  # 顯示聊天訊息的文字框 / Text area for chat messages
+        self.chat_panel.setLineWrapMode(self.chat_panel.LineWrapMode.NoWrap)  # 不自動換行 / Disable line wrap
+        self.chat_panel.setReadOnly(True)  # 設為唯讀，避免使用者直接輸入 / Read-only
+        self.chat_panel_scroll_area = QScrollArea()  # 加入滾動區域 / Scroll area for chat panel
         self.chat_panel_scroll_area.setWidgetResizable(True)
         self.chat_panel_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.chat_panel_scroll_area.setWidget(self.chat_panel)
-        self.chat_panel.setFont(QFontDatabase.font(self.font().family(), "", 16))
-        # Prompt input
-        self.prompt_input = QLineEdit()
+        self.chat_panel.setFont(QFontDatabase.font(self.font().family(), "", 16))  # 設定字體大小 / Set font size
+
+        # ---------------- Prompt Input 輸入框 ----------------
+        self.prompt_input = QLineEdit()  # 使用者輸入提示詞 / Input field for prompts
         self.prompt_input.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Minimum)
-        self.prompt_input.returnPressed.connect(self.call_ai_model)
-        # Font size combobox
-        self.font_size_label = QLabel(language_wrapper.language_word_dict.get("font_size"))
-        self.font_size_combobox = QComboBox()
-        for font_size in range(2, 101, 2):
+        self.prompt_input.returnPressed.connect(self.call_ai_model)  # 按 Enter 時呼叫 AI / Call AI on Enter
+
+        # ---------------- Font Size Combobox 字體大小選單 ----------------
+        self.font_size_label = QLabel(language_wrapper.language_word_dict.get("font_size"))  # 標籤 / Label
+        self.font_size_combobox = QComboBox()  # 下拉選單 / Dropdown for font size
+        for font_size in range(2, 101, 2):  # 提供 2~100 的字體大小選項 / Font size options
             self.font_size_combobox.addItem(str(font_size))
-        self.font_size_combobox.setCurrentText("16")
+        self.font_size_combobox.setCurrentText("16")  # 預設字體大小 / Default font size
         self.font_size_combobox.currentTextChanged.connect(self.update_panel_text_size)
-        # Buttons
+
+        # ---------------- Buttons 按鈕 ----------------
         self.set_ai_config_button = QPushButton(language_wrapper.language_word_dict.get("chat_ui_set_ai_button"))
-        self.set_ai_config_button.clicked.connect(self.set_ai_config)
+        self.set_ai_config_button.clicked.connect(self.set_ai_config)  # 開啟 AI 設定視窗 / Open AI config dialog
+
         self.load_ai_config_button = QPushButton(language_wrapper.language_word_dict.get("chat_ui_load_ai_button"))
-        self.load_ai_config_button.clicked.connect(lambda: self.load_ai_config(show_load_complete=True))
+        self.load_ai_config_button.clicked.connect(lambda: self.load_ai_config(show_load_complete=True))  # 載入設定 / Load config
+
         self.call_ai_model_button = QPushButton(language_wrapper.language_word_dict.get("chat_ui_call_ai_model_button"))
-        self.call_ai_model_button.clicked.connect(self.call_ai_model)
-        # Add to layout
+        self.call_ai_model_button.clicked.connect(self.call_ai_model)  # 呼叫 AI / Call AI
+
+        # ---------------- Layout 版面配置 ----------------
         self.grid_layout = QGridLayout()
-        self.grid_layout.addWidget(self.chat_panel_scroll_area, 0, 0, 1, 4)
-        self.grid_layout.addWidget(self.call_ai_model_button, 1, 0)
-        self.grid_layout.addWidget(self.font_size_combobox, 1, 1)
-        self.grid_layout.addWidget(self.set_ai_config_button, 1, 2)
-        self.grid_layout.addWidget(self.load_ai_config_button, 1, 3)
-        self.grid_layout.addWidget(self.prompt_input, 2, 0, 1, 4)
-
-        # Variable
-        self.ai_config: AIConfig = ai_config
-        self.lang_chain_interface: Union[LangChainInterface, None] = None
-        self.set_ai_config_dialog = None
-        # Timer to pop queue
-        self.pull_message_timer = QTimer(self)
-        self.pull_message_timer.setInterval(1000)
+        self.grid_layout.addWidget(self.chat_panel_scroll_area, 0, 0, 1, 4)  # 聊天面板 / Chat panel
+        self.grid_layout.addWidget(self.call_ai_model_button, 1, 0)  # 呼叫 AI 按鈕 / Call AI button
+        self.grid_layout.addWidget(self.font_size_combobox, 1, 1)  # 字體大小選單 / Font size combobox
+        self.grid_layout.addWidget(self.set_ai_config_button, 1, 2)  # 設定 AI 按鈕 / Set AI config button
+        self.grid_layout.addWidget(self.load_ai_config_button, 1, 3)  # 載入設定按鈕 / Load AI config button
+        self.grid_layout.addWidget(self.prompt_input, 2, 0, 1, 4)  # 輸入框 / Prompt input
+
+        # ---------------- Variables 變數 ----------------
+        self.ai_config: AIConfig = ai_config  # AI 設定物件 / AI config object
+        self.lang_chain_interface: Union[LangChainInterface, None] = None  # LangChain 介面 / LangChain interface
+        self.set_ai_config_dialog = None  # 設定對話框 / Config dialog
+
+        # ---------------- Timer 計時器 ----------------
+        self.pull_message_timer = QTimer(self)  # 定時檢查訊息佇列 / Timer to pull messages
+        self.pull_message_timer.setInterval(1000)  # 每秒檢查一次 / Check every 1 second
         self.pull_message_timer.timeout.connect(self.pull_message)
         self.pull_message_timer.start()
 
-        # Set layout
+        # ---------------- Set Layout 設定版面 ----------------
         self.setLayout(self.grid_layout)
 
+        # ---------------- Load AI Config 載入 AI 設定 ----------------
         self.load_ai_config()
 
+    # 更新聊天面板字體大小 / Update chat panel font size
     def update_panel_text_size(self):
         self.chat_panel.setFont(
             QFontDatabase.font(self.font().family(), "", int(self.font_size_combobox.currentText())))
 
+    # 載入 AI 設定檔 / Load AI configuration file
     def load_ai_config(self, show_load_complete: bool = False):
         ai_config_file = Path(str(Path.cwd()) + "/" + ".jeditor/ai_config.json")
         if ai_config_file.exists():
             with open(ai_config_file, "r", encoding="utf-8"):
                 json_data: dict = read_json(str(ai_config_file))
             if json_data:
+                # 確認 AI_model 設定存在且格式正確 / Ensure AI_model config exists and valid
                 if json_data.get("AI_model") and len(json_data.get("AI_model")) == 4:
                     ai_info: dict = json_data.get("AI_model")
                     if ai_info.get("ai_base_url") and ai_info.get("chat_model"):
-                        ai_config.choosable_ai.update(json_data)
+                        ai_config.choosable_ai.update(json_data)  # 更新全域設定 / Update global config
+                    # 建立 LangChain 介面 / Initialize LangChain interface
                     self.lang_chain_interface = LangChainInterface(
                         main_window=self,
                         api_key=ai_info.get("ai_api_key"),
@@ -103,12 +116,14 @@ class ChatUI(QWidget):
                 load_complete.setText(language_wrapper.language_word_dict.get("load_ai_messagebox_text"))
                 load_complete.exec()
 
-
+    # 呼叫 AI 模型 / Call AI model
     def call_ai_model(self):
         if isinstance(self.lang_chain_interface, LangChainInterface):
+            # 建立新執行緒處理 AI 請求 / Start a new thread for AI request
             thread = AskThread(lang_chain_interface=self.lang_chain_interface, prompt=self.prompt_input.text())
             thread.start()
         else:
+            # 若未正確設定 AI，顯示錯誤訊息 / Show error if AI not configured
             ai_info = ai_config.choosable_ai.get('AI_model')
             QMessageBox.warning(self,
                                 language_wrapper.language_word_dict.get("call_ai_model_error_title"),
@@ -118,13 +133,13 @@ class ChatUI(QWidget):
                                     f"chat_model: {ai_info.get('chat_model')}, \n"
                                     f"prompt_template: {ai_info.get('prompt_template')}"))
 
+    # 從訊息佇列中取出 AI 回覆並顯示 / Pull AI response from queue
     def pull_message(self):
         if not ai_config.message_queue.empty():
             ai_response = ai_config.message_queue.get_nowait()
-            self.chat_panel.appendPlainText(ai_response)
+            self.chat_panel.appendPlainText(ai_response)  # 顯示回覆 / Display response
             self.chat_panel.appendPlainText("\n")
 
+    # 開啟 AI 設定對話框 / Open AI config dialog
     def set_ai_config(self):
-        # Set and output AI a config file
-        self.set_ai_config_dialog = SetAIDialog()
-        self.set_ai_config_dialog.show()
+        self.set_ai_config

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()