feat: 新增WEB_PORT環境變數以自訂WebGUI埠號，並更新相關文檔說明

closed #56

.env.example

@@ -23,6 +23,9 @@ TEMPLATES_USE=en
 # Default is false.
 ENABLE_GUI=false
 
+# WebGUI port
+WEB_PORT=3000
+
 # ============================
 # Prompt Customization
 # ============================

README.md

@@ -42,7 +42,7 @@ Shrimp Task Manager guides Agents through structured workflows for systematic pr
 - **Task Memory Function**: Automatically backup task history, providing long-term memory and reference capabilities
 - **Research Mode**: Systematic technical research capabilities with guided workflows for exploring technologies, best practices, and solution comparisons
 - **Project Rules Initialization**: Define project standards and rules to maintain consistency across large projects
-- **<a id="web-gui"></a>Web GUI**: Provides an optional web-based graphical user interface for task management. Enable by setting `ENABLE_GUI=true` in your `.env` file. When enabled, a `WebGUI.md` file containing the access address will be created in your `DATA_DIR`.
+- **<a id="web-gui"></a>Web GUI**: Provides an optional web-based graphical user interface for task management. Enable by setting `ENABLE_GUI=true` in your `.env` file. When enabled, a `WebGUI.md` file containing the access address will be created in your `DATA_DIR`. You can customize the web port by setting `WEB_PORT` (if not specified, an available port will be automatically selected).
 
 ## 🧭 <a id="usage-guide"></a>Usage Guide
 
@@ -254,6 +254,8 @@ or
 ```
 
 > ⚠️ Please replace `/mcp-shrimp-task-manager` with your actual path.
+>
+> 💡 **Optional:** You can add `"WEB_PORT": "3000"` to the `env` section to specify a custom port for the web GUI. If not specified, an available port will be automatically selected.
 
 #### Project-Specific Configuration
 
@@ -295,6 +297,8 @@ or
 }
 ```
 
+> 💡 **Optional:** You can add `"WEB_PORT": "3000"` to the `env` section to specify a custom port for the web GUI. If not specified, an available port will be automatically selected.
+
 ### ⚠️ Important Configuration Notes
 
 The **DATA_DIR parameter** is the directory where Shrimp Task Manager stores task data, conversation logs, and other information. Setting this parameter correctly is crucial for the normal operation of the system. This parameter must use an **absolute path**; using a relative path may cause the system to incorrectly locate the data directory, resulting in data loss or function failure.
@@ -336,7 +340,9 @@ There are two customization methods:
 Additionally, there are other system configuration variables:
 
 - **DATA_DIR**: Specifies the directory where task data is stored
-- **TEMPLATES_USE**: Specifies the template set to use for prompts. Defaults to `en`. Currently available options are `en` and `zh`. To use custom templates, copy the `src/prompts/templates_en` directory to the location specified by `DATA_DIR`, rename the copied directory (e.g., to `my_templates`), and set `TEMPLATES_USE` to the new directory name (e.g., `my_templates`).
+- **TEMPLATES_USE**: Specifies the template set to use for prompts. Defaults to `en`. Currently available options are `en` and `zh`. To use custom templates, copy the `src/prompts/templates_en` directory to the location specified by `DATA_DIR`, rename the copied directory (e.g., to `my_templates`), and set `TEMPLATES_USE` to the new directory name (e.g., `my_templates`)
+- **ENABLE_GUI**: Enables or disables the web-based graphical user interface. Set to `true` to enable, `false` to disable (default)
+- **WEB_PORT**: Specifies the port for the web GUI. If not specified, an available port will be automatically selected. Only takes effect when `ENABLE_GUI` is set to `true`
 
 For detailed instructions on customizing prompts, including supported parameters and examples, see the [Prompt Customization Guide](docs/en/prompt-customization.md).
 

docs/zh/README.md

@@ -39,7 +39,7 @@
 - **思維鏈過程**：通過步驟化的推理系統性地分析複雜問題
 - **研究模式**：系統性技術研究功能，提供引導式工作流程來探索技術、最佳實踐和解決方案比較
 - **專案規範初始化**：定義專案標準和規則，維持大型專案的一致性
-- **<a id="網頁圖形介面"></a>網頁圖形介面**：提供選用的網頁圖形化使用者介面來管理任務。透過在您的 `.env` 檔案中設定 `ENABLE_GUI=true` 來啟用。啟用後，將會在您的 `DATA_DIR` 中建立一個包含存取網址的 `WebGUI.md` 檔案。
+- **<a id="網頁圖形介面"></a>網頁圖形介面**：提供選用的網頁圖形化使用者介面來管理任務。透過在您的 `.env` 檔案中設定 `ENABLE_GUI=true` 來啟用。啟用後，將會在您的 `DATA_DIR` 中建立一個包含存取網址的 `WebGUI.md` 檔案。您可以透過設定 `WEB_PORT` 來自訂網頁埠號（若未指定，系統將自動選擇可用的埠號）。
 
 ## 🧭 <a id="使用指南"></a>使用指南
 
@@ -250,6 +250,8 @@ or
 ```
 
 > ⚠️ 請將 `/mcp-shrimp-task-manager` 替換為您的實際路徑。
+>
+> 💡 **可選設定：** 您可以在 `env` 區段中添加 `"WEB_PORT": "3000"` 來指定網頁 GUI 的自訂埠號。若未指定，系統將自動選擇可用的埠號。
 
 #### 專案特定配置
 
@@ -290,6 +292,8 @@ or
 }
 ```
 
+> 💡 **可選設定：** 您可以在 `env` 區段中添加 `"WEB_PORT": "3000"` 來指定網頁 GUI 的自訂埠號。若未指定，系統將自動選擇可用的埠號。
+
 ### ⚠️ 重要配置說明
 
 **DATA_DIR 參數**是蝦米任務管理器存儲任務數據、對話記錄等信息的目錄，正確設置此參數對於系統的正常運行至關重要。此參數必須使用**絕對路徑**，使用相對路徑可能導致系統無法正確定位數據目錄，造成數據丟失或功能失效。
@@ -331,7 +335,9 @@ or
 此外，還有其他系統配置變數：
 
 - **DATA_DIR**：指定任務數據存儲的目錄
-- **TEMPLATES_USE**：指定提示詞使用的模板集。預設為 `en`。目前可用的選項有 `en` 和 `zh`。若要使用自定義模板，請將 `src/prompts/templates_en` 目錄複製到 `DATA_DIR` 指定的位置，重新命名複製的目錄（例如，`my_templates`），並將 `TEMPLATES_USE` 設置為新的目錄名稱（例如，`my_templates`）。
+- **TEMPLATES_USE**：指定提示詞使用的模板集。預設為 `en`。目前可用的選項有 `en` 和 `zh`。若要使用自定義模板，請將 `src/prompts/templates_en` 目錄複製到 `DATA_DIR` 指定的位置，重新命名複製的目錄（例如，`my_templates`），並將 `TEMPLATES_USE` 設置為新的目錄名稱（例如，`my_templates`）
+- **ENABLE_GUI**：啟用或停用網頁圖形化使用者介面。設定為 `true` 以啟用，`false` 以停用（預設）
+- **WEB_PORT**：指定網頁 GUI 的埠號。若未指定，系統將自動選擇可用的埠號。僅在 `ENABLE_GUI` 設定為 `true` 時生效
 
 有關自定義提示詞的詳細說明，包括支援的參數和範例，請參閱[提示詞自定義指南](prompt-customization.md)。
 

src/index.ts

@@ -126,7 +126,7 @@ async function main() {
       });
 
       // 獲取可用埠
-      const port = await getPort();
+      const port = process.env.WEB_PORT || (await getPort());
 
       // 啟動 HTTP 伺服器
       const httpServer = app.listen(port, () => {