@hirohsu/user-web-feedback 2.6.0

package/README.md

@@ -0,0 +1,953 @@
+# 🎯 MCP 使用者反饋收集器
+
+[![npm version](https://badge.fury.io/js/%40hirohsu%2Fuser-web-feedback.svg)](https://www.npmjs.com/package/@hirohsu/user-web-feedback)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+基於 Node.js 的現代化 MCP 反饋收集器，支援 AI 工作匯報和使用者反饋收集。
+---
+** 這是 Fork 自三少科技的專案 ** (https://github.com/sanshao85/mcp-feedback-collector-web)
+感謝三少科技的無私奉獻
+
+## 🆕 增強版反饋介面
+
+**全新的增強版使用者介面現已推出！**
+
+### 🌟 核心特性
+
+#### 🎨 三欄式佈局設計
+- **左側（30%）**：AI 工作匯報顯示區
+  - 支援 Markdown 渲染
+  - 程式碼語法高亮
+  - 可捲動查看歷史訊息
+  
+- **中間（40%）**：使用者互動區
+  - 文字回應輸入（支援 Ctrl+Enter 快速提交）
+  - 圖片上傳/貼上功能
+  - AI 輔助回覆按鈕
+  - 即時連接狀態顯示（底部中央）
+  
+- **右側（30%）**：提示詞管理區
+  - 提示詞 CRUD 操作
+  - 搜尋和過濾功能
+  - 釘選常用提示詞
+  - AI 設定管理
+
+#### 🤖 AI 輔助回覆（Gemini API）
+- 整合 Google Gemini 2.5 Flash API
+- 根據 AI 工作匯報自動生成建議回覆
+- 可自訂系統提示詞
+- 智能重試機制和錯誤處理
+- 支援溫度參數和最大 token 數調整
+
+#### 📝 提示詞管理系統
+- **CRUD 操作**：創建、讀取、更新、刪除提示詞
+- **釘選功能**：釘選常用提示詞，啟動時自動載入
+- **分類管理**：支援提示詞分類（選填）
+- **搜尋過濾**：快速找到需要的提示詞
+- **順序調整**：拖拽調整提示詞顯示順序
+- **點擊插入**：點擊提示詞快速插入到輸入區
+
+#### ⏰ 自動回覆機制
+- **5 分鐘無活動**：自動觸發 AI 回覆
+- **60 秒倒數警告**：提前通知使用者
+- **可取消**：使用者可隨時取消自動回覆
+- **可調整超時**：通過使用者偏好設定調整超時時間
+
+#### 🔒 資料加密保護
+- **AES-256-GCM 加密**：保護 API Key 等敏感資料
+- **SQLite 本地儲存**：所有資料本地化儲存
+- **密碼派生**：使用 scrypt 從主密碼派生加密金鑰
+- **遮罩顯示**：前端僅顯示 API Key 的遮罩版本
+
+#### 🔌 MCP Server 整合
+- **多 Server 支援**：同時連接多個 MCP Server
+- **三種傳輸方式**：stdio、SSE、Streamable HTTP
+- **AI 工具呼叫**：AI 自動識別並呼叫 MCP 工具
+- **多輪執行**：最多 5 輪自動工具呼叫
+- **進度指示**：即時顯示工具執行狀態
+
+#### 🎯 使用者體驗優化
+- **響應式設計**：支援各種螢幕尺寸
+- **快捷鍵支援**：Ctrl+Enter 提交、Ctrl+V 貼上圖片
+- **即時連接狀態**：WebSocket 連接狀態實時顯示（底部中央對齊）
+- **錯誤提示**：友善的錯誤訊息和操作指引
+- **自動儲存**：使用者偏好和設定自動保存
+
+### 📖 詳細文檔
+
+完整的使用說明請參閱：[增強版反饋介面指南](.docs/ENHANCED_FEEDBACK_GUIDE.md)
+
+### 🚀 訪問增強版介面
+
+```
+http://localhost:3000/index.html
+```
+
+---
+
+## ✨ 標準版特性
+
+- 🚀 **一鍵啟動**：使用 `npx @hirohsu/user-web-feedback` 直接運行
+- 🎨 **現代界面**：VS Code 深色主題風格的 Web 界面
+- 🔧 **MCP 整合**：完整支援 Model Context Protocol
+- 💬 **AI 對話功能**：整合 AI 助手，支援文字和圖片對話
+- 🖼️ **圖片支援**：完整的圖片上傳、處理和顯示功能
+- 📄 **圖片轉文字**：AI 智能圖片描述，提升客戶端兼容性
+- 🌐 **跨平台**：支援 Windows、macOS、Linux
+- ⚡ **高效能**：解決了 Python 版本的穩定性問題
+
+---
+
+## 📚 教學資源
+
+### 開發過程視頻教程
+- **YouTube**：https://youtu.be/Osr1OSMgzlg
+- **Bilibili**：https://www.bilibili.com/video/BV1PHTxzSErb/
+
+---
+
+## 🚀 快速開始
+
+### 安裝和運行
+
+```bash
+# 直接運行（推薦）
+npx @hirohsu/user-web-feedback
+
+# 或者全局安裝
+npm install -g @hirohsu/user-web-feedback
+user-web-feedback
+
+# 檢查版本
+user-web-feedback --version
+```
+
+---
+
+## 📦 NPM 發行版本使用指南
+
+### 從 npm 安裝
+
+```bash
+# 全局安裝（推薦）
+npm install -g @hirohsu/user-web-feedback
+
+# 專案內安裝
+npm install @hirohsu/user-web-feedback
+```
+
+### 使用 npx 運行（無需安裝）
+
+```bash
+# 運行最新版本
+npx @hirohsu/user-web-feedback
+
+# 指定版本
+npx @hirohsu/user-web-feedback@2.2.0
+
+# 帶參數運行
+npx @hirohsu/user-web-feedback --port 8080
+```
+
+### 程式化使用
+
+```javascript
+// ESM 模組
+import { MCPServer, getConfig } from '@hirohsu/user-web-feedback';
+
+const config = getConfig();
+const server = new MCPServer(config);
+await server.start();
+```
+
+### 發行版本特性
+
+- ✅ **獨立運行**：編譯後的 `dist/` 目錄可獨立執行，無需原始碼
+- ✅ **安全發行**：不包含敏感資訊、開發檔案或原始碼
+- ✅ **版本一致**：CLI、API、Web 介面版本號自動同步
+- ✅ **跨平台**：支援 Windows、macOS、Linux
+
+---
+
+### 環境變數配置
+
+創建 `.env` 文件：
+
+```bash
+# AI API 配置
+MCP_API_KEY="your_api_key_here"
+MCP_API_BASE_URL="https://api.ssopen.top"  # 中轉站，也可使用 OpenAI 官方 API
+MCP_DEFAULT_MODEL="grok-3"
+
+# Web 服務器配置
+MCP_WEB_PORT="5000"
+MCP_DIALOG_TIMEOUT="60000"  # 反饋收集超時時間（秒），範圍：10-60000
+
+# 功能開關
+MCP_ENABLE_CHAT="true"
+MCP_ENABLE_IMAGE_TO_TEXT="true"  # 啟用圖片轉文字功能
+
+# 增強版介面專用配置
+MCP_ENCRYPTION_PASSWORD="your-secure-password"  # API Key 加密主密碼（強烈建議設定）
+
+# URL 和端口優化配置 (v2.0.7 新增)
+MCP_USE_FIXED_URL="true"           # 使用固定 URL，不帶會話參數 (預設: true)
+MCP_CLEANUP_PORT_ON_START="true"   # 啟動時清理端口 (預設: true)
+
+# 多實例支援 (v2.3.0 新增)
+# 當端口被佔用時，系統會自動遞增到下一個可用端口
+# 例如：5050 被佔用 → 自動使用 5051
+# 最多嘗試 20 個連續端口
+```
+
+---
+
+## 🔧 使用方法
+
+### 命令行選項
+
+```bash
+# 啟動服務器（預設）
+npx @hirohsu/user-web-feedback
+
+# 指定端口
+npx @hirohsu/user-web-feedback --port 8080
+
+# 僅 Web 模式
+npx @hirohsu/user-web-feedback --web
+
+# 測試 collect_feedback 功能
+npx @hirohsu/user-web-feedback test-feedback
+
+# 自訂測試內容
+npx @hirohsu/user-web-feedback test-feedback -m "我的工作匯報" -t 120
+
+# 健康檢查
+npx @hirohsu/user-web-feedback health
+
+# 顯示配置
+npx @hirohsu/user-web-feedback config
+```
+
+---
+
+## 🔌 Claude Desktop / Cursor 整合
+
+### 方式一：NPM 套件運行（推薦）
+
+在 Claude Desktop 或 Cursor 的 MCP 配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "command": "npx",
+      "args": ["-y", "@hirohsu/user-web-feedback@latest"],
+      "env": {
+        "MCP_API_KEY": "your_api_key_here",
+        "MCP_API_BASE_URL": "https://api.ssopen.top",
+        "MCP_DEFAULT_MODEL": "grok-3",
+        "MCP_WEB_PORT": "5050",
+        "MCP_DIALOG_TIMEOUT": "60000",
+        "MCP_ENABLE_IMAGE_TO_TEXT": "true",
+        "MCP_ENCRYPTION_PASSWORD": "your-secure-password"
+      }
+    }
+  }
+}
+```
+
+當使用自訂 register 時，請設定:
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "command": "npx",
+      "args": ["-y", "@hirohsu/user-web-feedback@latest", "--register", "http://localhost:5050"],
+      "env": {
+        "MCP_API_KEY": "your_api_key_here",
+        "MCP_API_BASE_URL": "https://api.ssopen.top",
+        "MCP_DEFAULT_MODEL": "grok-3",
+        "MCP_WEB_PORT": "5050",
+        "MCP_DIALOG_TIMEOUT": "60000",
+        "MCP_ENABLE_IMAGE_TO_TEXT": "true",
+        "MCP_ENCRYPTION_PASSWORD": "your-secure-password"
+      }
+    }
+  }
+}
+```
+
+
+### 方式二：原始碼運行（本地開發）
+
+如果您複製了原始碼並想直接運行：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "command": "node",
+      "args": ["path/to/your/project/dist/cli.js"],
+      "env": {
+        "MCP_API_KEY": "your_api_key_here",
+        "MCP_API_BASE_URL": "https://api.ssopen.top",
+        "MCP_DEFAULT_MODEL": "grok-3",
+        "MCP_WEB_PORT": "5050",
+        "MCP_DIALOG_TIMEOUT": "60000",
+        "MCP_ENCRYPTION_PASSWORD": "your-secure-password"
+      }
+    }
+  }
+}
+```
+
+**注意**：
+- 將 `path/to/your/project` 替換為您的實際專案路徑
+- 確保已運行 `npm run build` 構建專案
+- 使用絕對路徑，例如：`d:/zhuomian/nodejsweb/dist/cli.js`
+
+### 方式三：TypeScript 原始碼直接運行（開發模式）
+
+直接運行 TypeScript 原始碼而無需構建：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "command": "npx",
+      "args": ["tsx", "path/to/your/project/src/cli.ts"],
+      "env": {
+        "MCP_API_KEY": "your_api_key_here",
+        "MCP_API_BASE_URL": "https://api.ssopen.top",
+        "MCP_DEFAULT_MODEL": "grok-3",
+        "MCP_WEB_PORT": "5050",
+        "MCP_DIALOG_TIMEOUT": "60000",
+        "NODE_ENV": "development"
+      }
+    }
+  }
+}
+```
+
+**優點**：無需構建，直接運行原始碼  
+**缺點**：啟動稍慢，需要 tsx 依賴
+
+### 🚀 快速配置範例
+
+假設您的專案位於 `d:\zhuomian\nodejsweb`，推薦配置：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "command": "node",
+      "args": ["d:/zhuomian/nodejsweb/dist/cli.js"],
+      "env": {
+        "MCP_API_KEY": "your_api_key_here",
+        "MCP_API_BASE_URL": "https://api.ssopen.top",
+        "MCP_DEFAULT_MODEL": "grok-3",
+        "MCP_WEB_PORT": "5050",
+        "MCP_DIALOG_TIMEOUT": "60000"
+      }
+    }
+  }
+}
+```
+
+**配置步驟**：
+1. 確保專案已構建：`npm run build`
+2. 將上述配置添加到 Cursor 的 MCP 設定中
+3. 替換 `your_api_key_here` 為您的實際 API 密鑰
+4. 重啟 Cursor，查看 MCP 服務器狀態為綠色
+
+### 在 Cursor 規則中配置
+
+在 Cursor 的規則中可以這樣配置：
+
+```
+Whenever you want to ask a question, always call the MCP.
+
+Whenever you're about to complete a user request, call the MCP instead of simply ending the process. Keep calling MCP until the user's feedback is empty, then end the request. user-web-feedback.collect_feedback
+```
+
+### ⚠️ 重要提醒
+
+- **不要在 args 中添加 `--debug` 參數**，這會導致 JSON 解析失敗
+- Cursor/Claude Desktop 要求極其純淨的 JSON 輸出
+- 如需除錯，請在命令行中單獨使用：`npx @hirohsu/user-web-feedback --debug`
+
+### 💡 API 服務推薦
+
+- 預設配置使用 `https://api.ssopen.top` 中轉站，支援多種 AI 模型
+- 也可以使用 OpenAI 官方 API：`https://api.openai.com/v1`
+- 或其他相容 OpenAI 格式的 API 服務
+
+---
+
+## 🌐 HTTP 傳輸模式（Docker 部署）
+
+除了傳統的 stdio 傳輸模式，本系統現在支援 HTTP 傳輸模式（SSE 和 Streamable HTTP），使其能夠在 Docker 容器中運行並接受遠端 MCP 連線。
+
+### 傳輸模式說明
+
+| 模式 | 描述 | 適用場景 |
+|------|------|----------|
+| `stdio` | 標準輸入/輸出傳輸（預設） | 本地 MCP 客戶端（Claude Desktop、Cursor） |
+| `sse` | Server-Sent Events | Docker 部署、遠端連線 |
+| `streamable-http` | Streamable HTTP | Docker 部署、現代 HTTP 串流 |
+
+### 使用方式
+
+#### 命令列啟動
+
+```bash
+# 使用 SSE 傳輸模式
+npx @hirohsu/user-web-feedback --transport sse
+
+# 使用 Streamable HTTP 傳輸模式
+npx @hirohsu/user-web-feedback --transport streamable-http
+```
+
+#### 環境變數配置
+
+```bash
+# 設定傳輸模式
+MCP_TRANSPORT=sse  # 或 streamable-http
+```
+
+### Docker 部署
+
+#### 使用 Docker Compose（推薦）
+
+```bash
+# 啟動服務
+docker-compose up -d
+
+# 查看日誌
+docker-compose logs -f
+```
+
+#### 使用 Docker 直接運行
+
+```bash
+# 構建映像
+docker build -t user-feedback-web .
+
+# 運行容器
+docker run -d \
+  --name user-feedback-web \
+  -p 3000:3000 \
+  -e MCP_TRANSPORT=sse \
+  -e MCP_WEB_PORT=3000 \
+  -v ./data:/app/data \
+  user-feedback-web
+```
+
+### HTTP MCP Server 配置範例
+
+#### Claude Desktop / Cursor 配置（連接到 Docker 容器）
+
+使用 SSE 傳輸連接到運行中的 Docker 容器：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "transport": "sse",
+      "url": "http://localhost:3000/mcp/sse"
+    }
+  }
+}
+```
+
+使用 Streamable HTTP 傳輸：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "transport": "streamable-http",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+#### 遠端伺服器連接
+
+如果 Docker 容器運行在遠端伺服器：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "transport": "sse",
+      "url": "http://your-server-ip:3000/mcp/sse"
+    }
+  }
+}
+```
+
+### HTTP 端點說明
+
+| 端點 | 方法 | 描述 |
+|------|------|------|
+| `/mcp/sse` | GET | SSE 連線端點 |
+| `/mcp/message` | POST | SSE 訊息端點 |
+| `/mcp` | POST | Streamable HTTP 端點 |
+| `/health` | GET | 健康檢查端點 |
+
+### 注意事項
+
+1. **安全性**：HTTP 傳輸模式不包含內建認證，建議在生產環境中使用反向代理（如 nginx）添加 HTTPS 和認證。
+
+2. **網路配置**：確保防火牆允許對應端口的流量。
+
+3. **日誌**：可透過 `LOG_LEVEL` 環境變數調整日誌級別（debug、info、warn、error）。
+
+---
+
+## 🆕 最新功能 (v2.1.3+)
+
+### 🎨 增強版反饋介面（最新）
+
+**完整的介面重構**，提供專業級使用者體驗：
+
+- ✅ **三欄式佈局**：AI 訊息、使用者輸入、提示詞管理
+- ✅ **AI 輔助回覆**：整合 Gemini API，自動生成建議回覆
+- ✅ **提示詞管理**：CRUD 操作、釘選、搜尋、分類
+- ✅ **自動回覆機制**：5 分鐘無活動自動觸發 AI 回覆
+- ✅ **資料持久化**：SQLite 本地儲存
+- ✅ **API Key 加密**：AES-256-GCM 加密保護
+- ✅ **響應式設計**：支援各種螢幕尺寸
+- ✅ **即時連接狀態**：WebSocket 狀態顯示（底部中央）
+
+詳細說明：[增強版反饋介面指南](.docs/ENHANCED_FEEDBACK_GUIDE.md)
+
+### 📋 MCP 標準日誌功能
+
+- **完整日誌支援**：實現 MCP 協定標準的日誌功能，完全符合 MCP 規範
+- **多級別日誌**：支援 debug、info、notice、warning、error、critical、alert、emergency 八個標準級別
+- **客戶端控制**：支援 MCP 客戶端通過 `logging/setLevel` 請求動態設定日誌級別
+- **即時通知**：所有日誌自動通過 `notifications/message` 發送到 MCP 客戶端
+- **專業輸出**：移除表情符號，提供乾淨專業的日誌輸出，適合生產環境
+- **非同步處理**：優化日誌通知的非同步處理，避免未處理的 Promise 拒絕錯誤
+- **智能過濾**：根據設定的日誌級別智能過濾輸出內容
+
+### 🔧 重大改進：智能端口衝突解決方案
+
+- **智能端口管理**：自動檢測和解決端口衝突，無需手動介入
+- **漸進式進程終止**：優雅終止 → 強制終止 → 多種備用方案
+- **自進程識別**：能準確識別和清理自己的僵尸進程
+- **跨平台相容**：Windows/macOS/Linux 統一處理機制
+- **智能降級**：無法清理時自動尋找替代端口
+
+### 🛡️ 優雅退出處理
+
+- **完整信號處理**：支援 SIGINT、SIGTERM、SIGBREAK（Windows）
+- **智能異常處理**：優化未捕獲異常和 Promise 拒絕的處理機制
+- **防重複關閉**：添加關閉狀態標誌，避免重複執行關閉流程
+- **客戶端通知**：關閉前通知所有連接的客戶端
+- **資源清理**：確保所有資源正確釋放，避免僵尸進程
+
+### 🚀 使用者體驗提升
+
+- **詳細日誌**：清晰的進程終止和端口釋放日誌，支援 MCP 標準日誌輸出
+- **自動處理**：大部分端口衝突自動解決，智能降級策略
+- **智能提示**：明確的狀態提示和錯誤訊息，專業化輸出格式
+- **無縫體驗**：使用者無需關心底層端口管理和日誌配置
+- **開發友善**：完整的 MCP 協定支援，便於整合和除錯
+
+### 📄 圖片轉文字功能 (v2.1.1)
+
+- **智能圖片描述**：AI 自動將圖片轉換為詳細文字描述
+- **相容性提升**：解決部分 MCP 客戶端無法顯示圖片的問題
+- **使用者可控**：點擊「圖片轉文本」按鈕主動轉換
+- **可編輯描述**：使用者可以修改 AI 生成的圖片描述
+- **批次處理**：支援多張圖片同時轉換
+
+### 🎨 UI 簡化優化 (v2.1.1)
+
+- **純文字狀態顯示**：移除旋轉動畫，簡潔直觀
+- **智能自動刷新**：預設啟用，無需使用者選擇
+- **簡約設計**：符合現代 UI 設計趨勢
+
+### 🔄 會話管理優化 (v2.1.1)
+
+- **智能頁面刷新**：檢測新內容時自動刷新頁面
+- **會話自動重置**：解決「對話過期」問題
+- **無縫體驗**：3 秒倒數提示
+
+### 🔗 固定 URL 模式 (v2.0.7)
+
+- 使用固定根路徑：`http://localhost:5000`
+- 支援多個並發會話
+- 便於遠端服務器轉發
+
+---
+
+## 🛠️ MCP 工具函數
+
+### collect_feedback
+
+收集使用者對 AI 工作的反饋：
+
+```typescript
+// 基本呼叫（超時時間從環境變數讀取）
+collect_feedback("我已經完成了程式碼重構工作，主要改進了效能和可讀性。")
+```
+
+**參數說明**：
+- `work_summary`（必需）：AI 工作匯報內容
+
+**超時時間配置**：
+- 超時時間通過環境變數 `MCP_DIALOG_TIMEOUT` 統一配置
+- 預設值為 60000 秒（約 16.7 小時）
+- 有效範圍：10-60000 秒
+
+**功能**：
+- 啟動 Web 界面顯示工作匯報
+- 收集使用者文字和圖片反饋
+- 返回結構化的反饋資料
+- 自動管理服務器生命週期
+- 提交反饋後自動關閉標籤頁（3 秒倒數）
+
+### 📋 MCP 日誌功能
+
+本專案完全支援 MCP 協定標準的日誌功能，提供專業級的日誌管理：
+
+**服務器能力聲明**：
+- 在 MCP 初始化時自動聲明 `logging` 能力
+- 完全符合 MCP 協定規範，支援所有標準日誌級別
+- 提供動態日誌級別控制和即時通知功能
+
+**支援的日誌級別**（按優先級排序）：
+- `emergency` - 緊急情況，系統不可用
+- `alert` - 警報資訊，需要立即處理
+- `critical` - 關鍵錯誤，嚴重問題
+- `error` - 錯誤資訊，功能異常
+- `warning` - 警告資訊，潛在問題
+- `notice` - 通知資訊，重要事件
+- `info` - 一般資訊，常規操作
+- `debug` - 除錯資訊，詳細追蹤
+
+**客戶端控制**：
+```json
+{
+  "method": "logging/setLevel",
+  "params": {
+    "level": "info"
+  }
+}
+```
+
+**日誌通知格式**：
+```json
+{
+  "method": "notifications/message",
+  "params": {
+    "level": "info",
+    "logger": "user-web-feedback",
+    "data": {
+      "message": "服務器啟動成功",
+      "port": 5000,
+      "url": "http://localhost:5000"
+    }
+  }
+}
+```
+
+**技術特性**：
+- **非同步處理**：優化的非同步日誌處理，避免阻塞主執行緒
+- **錯誤恢復**：完善的錯誤處理機制，避免日誌系統影響主功能
+- **智能過濾**：根據設定的級別自動過濾日誌輸出
+- **結構化資料**：支援複雜物件的日誌記錄，便於除錯分析
+
+這使得 Claude Desktop、Cursor 等 MCP 客戶端能夠接收和處理服務器的日誌資訊，大大提升了開發和除錯體驗。
+
+---
+
+## 🎨 界面特性
+
+### 增強版介面
+- **三欄式佈局**：AI 訊息 + 使用者輸入 + 提示詞管理
+- **Markdown 渲染**：完整支援 Markdown 語法和程式碼高亮
+- **響應式設計**：支援各種螢幕尺寸
+- **即時連接狀態**：WebSocket 連接狀態即時顯示（底部中央對齊）
+- **多模態支援**：文字 + 圖片組合輸入
+- **智能提示**：友善的錯誤訊息和操作指引
+
+### 標準版介面
+- **雙標籤頁設計**：工作匯報 + AI 對話
+- **VS Code 主題**：深色主題，專業美觀
+- **響應式佈局**：支援桌面和行動裝置
+- **即時通信**：WebSocket 連接狀態指示
+- **多模態支援**：文字 + 圖片組合輸入
+- **智能提交確認**：使用者可選擇提交後是否關閉頁面
+- **靈活操作**：支援取消提交和多種互動方式
+
+---
+
+## 📋 系統要求
+
+- **Node.js**：18.0.0 或更高版本
+- **瀏覽器**：Chrome 90+、Firefox 88+、Safari 14+、Edge 90+
+- **作業系統**：Windows 10+、macOS 10.15+、Ubuntu 18.04+
+
+---
+
+## 🔒 安全特性
+
+### 增強版介面專用
+- **AES-256-GCM 加密**：保護 API Key 等敏感資料
+- **密碼派生**：使用 scrypt 從主密碼派生加密金鑰
+- **本地儲存**：SQLite 本地資料庫，不上傳至雲端
+- **遮罩顯示**：前端僅顯示 API Key 的部分字元
+
+### 通用安全
+- 輸入驗證和檔案大小限制
+- CORS 配置和安全標頭
+- API 密鑰安全儲存
+- 惡意內容基礎檢測
+
+---
+
+## 📊 效能指標
+
+- **啟動時間**：< 3 秒
+- **記憶體使用**：< 100MB
+- **回應時間**：< 2 秒
+- **並發連接**：支援 10 個同時連接
+
+---
+
+## 🐛 故障排除
+
+### 增強版介面相關
+
+#### 問題：API Key 驗證失敗
+**解決方法**：
+1. 檢查 API Key 是否正確
+2. 確認模型名稱是否有效（例如：`gemini-2.0-flash-exp`）
+3. 檢查網路連接
+4. 查看瀏覽器控制台的錯誤訊息
+5. 確認 API URL 是否正確（預設：`https://generativelanguage.googleapis.com/v1beta`）
+
+#### 問題：資料庫初始化失敗
+**解決方法**：
+1. 檢查 `data` 目錄的寫入權限
+2. 確認沒有其他程序正在使用資料庫檔案
+3. 刪除損壞的資料庫檔案（`data/feedback.db`）並重新啟動
+
+#### 問題：自動回覆未觸發
+**解決方法**：
+1. 檢查使用者偏好設定中是否啟用自動回覆
+2. 確認 AI 設定已正確配置（API Key、模型名稱）
+3. 查看服務器日誌的錯誤訊息
+4. 確認網路連接正常
+
+#### 問題：提示詞無法儲存
+**解決方法**：
+1. 檢查資料庫連接狀態
+2. 嘗試刷新頁面
+3. 查看瀏覽器控制台的錯誤訊息
+4. 確認 `data` 目錄有寫入權限
+
+### 標準版介面相關
+
+#### 1. WebSocket 連接失敗
+```bash
+# 檢查服務器狀態
+npx @hirohsu/user-web-feedback health
+
+# 訪問測試頁面
+http://localhost:5000/test.html
+
+# 查看瀏覽器控制台錯誤訊息
+```
+
+#### 2. 端口被占用
+```bash
+# 檢查端口使用情況
+netstat -an | grep :5000
+
+# 使用其他端口
+npx @hirohsu/user-web-feedback --port 5001
+```
+
+#### 3. API 密鑰錯誤
+```bash
+# 檢查配置
+npx @hirohsu/user-web-feedback config
+
+# 設定環境變數
+export MCP_API_KEY="your_key_here"
+```
+
+#### 4. 權限問題
+```bash
+# 使用 npx 避免全域安裝權限問題
+npx @hirohsu/user-web-feedback
+```
+
+詳細的故障排除指南請參考：[TROUBLESHOOTING.md](.docs/TROUBLESHOOTING.md)
+
+---
+
+## 📚 完整文檔
+
+本專案提供了完整的文檔體系，請參考 [📚 文檔索引](.docs/DOCUMENTATION_INDEX.md) 查找您需要的資訊：
+
+- **使用者指南**：[USER_GUIDE.md](.docs/USER_GUIDE.md) - 詳細使用說明
+- **增強版指南**：[ENHANCED_FEEDBACK_GUIDE.md](.docs/ENHANCED_FEEDBACK_GUIDE.md) - 增強版介面專用指南
+- **配置指南**：[CONFIGURATION.md](.docs/CONFIGURATION.md) - 環境變數配置
+- **技術文檔**：[ARCHITECTURE.md](.docs/ARCHITECTURE.md) - 系統架構設計
+- **故障排除**：[TROUBLESHOOTING.md](.docs/TROUBLESHOOTING.md) - 問題解決方案
+- **版本說明**：[RELEASE_NOTES.md](.docs/RELEASE_NOTES.md) - 版本更新記錄
+- **開發文檔**：[DEVELOPMENT.md](.docs/DEVELOPMENT.md) - 開發環境搭建和貢獻指南
+- **技術文檔**：[TECHNICAL.md](.docs/TECHNICAL.md) - 系統架構和技術細節
+- **更新日誌**：[CHANGELOG.md](.docs/CHANGELOG.md) - 版本變更歷史
+
+---
+
+## 📝 開發
+
+### 本地開發
+
+```bash
+# 複製專案
+git clone https://github.com/sanshao85/user-web-feedback-web.git
+cd user-web-feedback-web
+
+# 安裝依賴
+npm install
+
+# 開發模式（即時編譯 TypeScript）
+npm run dev
+
+# 構建專案（生成 dist 目錄）
+npm run build
+
+# 啟動已構建的專案
+npm start
+
+# 測試
+npm test
+
+# 健康檢查
+npm start health
+
+# 顯示配置
+npm start config
+```
+
+### MCP 配置測試
+
+構建完成後，您可以使用以下配置在 Cursor 中測試：
+
+```json
+{
+  "mcpServers": {
+    "user-web-feedback": {
+      "command": "node",
+      "args": ["您的專案路徑/dist/cli.js"],
+      "env": {
+        "MCP_API_KEY": "your_api_key_here",
+        "MCP_API_BASE_URL": "https://api.ssopen.top",
+        "MCP_DEFAULT_MODEL": "grok-3",
+        "MCP_WEB_PORT": "5050",
+        "MCP_DIALOG_TIMEOUT": "180",
+        "MCP_ENCRYPTION_PASSWORD": "your-secure-password"
+      }
+    }
+  }
+}
+```
+
+### 專案結構
+
+```
+src/
+├── cli.ts                    # CLI 入口
+├── index.ts                  # 主入口
+├── config/                   # 配置管理
+├── server/                   # 服務器實現
+│   ├── mcp-server.ts        # MCP 服務器
+│   └── web-server.ts        # Web 服務器（增強版 API）
+├── utils/                    # 工具函數
+│   ├── crypto-helper.ts     # 加密工具（增強版）
+│   ├── database.ts          # 資料庫工具（增強版）
+│   └── ai-service.ts        # AI 服務（增強版）
+├── types/                    # 類型定義
+│   └── index.ts             # TypeScript 介面
+└── static/                   # 靜態檔案
+    ├── index.html           # 增強版介面（主入口）
+    ├── style.css            # 增強版樣式
+    ├── app.js               # 增強版邏輯
+    ├── index-enhanced.html  # 舊版檔案（備用）
+    ├── style-enhanced.css   # 舊版樣式（備用）
+    └── app-enhanced.js      # 舊版邏輯（備用）
+```
+
+---
+
+## 📊 專案狀態
+
+- **當前版本**：v2.1.3+（增強版介面）
+- **維護狀態**：積極維護
+- **支援平台**：Windows、macOS、Linux
+- **最新特性**：增強版反饋介面（三欄式佈局、AI 輔助、提示詞管理、自動回覆、資料加密）
+- **協定支援**：MCP v2025-03-26、v2024-11-05、v2024-10-07
+- **SDK 版本**：@modelcontextprotocol/sdk v1.12.1
+
+---
+
+## 📄 授權
+
+MIT License - 詳見 [LICENSE](LICENSE) 檔案
+
+---
+
+## 🤝 貢獻
+
+歡迎提交 Issue 和 Pull Request！
+
+1. Fork 本儲存庫
+2. 創建您的特性分支（`git checkout -b feature/AmazingFeature`）
+3. 提交您的更改（`git commit -m 'Add some AmazingFeature'`）
+4. 推送到分支（`git push origin feature/AmazingFeature`）
+5. 打開一個 Pull Request
+
+---
+
+## 🔗 相關連結
+
+- **原始專案主頁**：[GitHub Repository](hhttps://github.com/sanshao85/mcp-feedback-collector-web)
+- **NPM 套件**：[@hirohsu/user-web-feedback](https://www.npmjs.com/package/@hirohsu/user-web-feedback)
+- **Model Context Protocol**：[官方網站](https://modelcontextprotocol.io)
+- **MCP 規範**：[技術規範](https://spec.modelcontextprotocol.io)
+- **Claude Desktop**：[下載地址](https://claude.ai/desktop)
+
+---
+
+## 💝 感謝支持
+
+特別感謝 [https://api.ssopen.top/](https://api.ssopen.top/) API 中轉站，提供 290+ AI 大模型，官方成本七分之一，支援高並發！
+
+---
+
+## 🚀 快速導航
+
+- 🆕 [增強版介面指南](.docs//ENHANCED_FEEDBACK_GUIDE.md) - **最新功能**
+- 📖 [使用者指南](.docs/USER_GUIDE.md) - 標準版使用說明
+- 🔧 [配置指南](.docs/CONFIGURATION.md) - 環境變數設定
+- 🐛 [故障排除](.docs/TROUBLESHOOTING.md) - 常見問題解答
+- 🏗️ [技術架構](.docs/ARCHITECTURE.md) - 系統設計文檔
+- 📝 [更新日誌](.docs/CHANGELOG.md) - 版本變更歷史
+
+---
+
+**立即體驗增強版介面**：`http://localhost:3000/index.html` 🎉