Gorev

🚀 Gorev

Gorev 是一款支持土耳其語的現代任務管理系統，專為與 MCP 兼容的 AI 助手（如 Claude、VS Code、Windsurf、Cursor 等）設計。它藉助強大的 AI 助手，將項目管理、任務跟蹤和組織需求相結合，有效提升用戶的工作效率。

⚠️ 重要提示

本項目目前正在 積極開發 中，可能會頻繁出現重大變更、API 修改和功能更新。請謹慎在生產環境中使用。

最後更新時間：2025 年 11 月 28 日 | 版本：v0.17.0

🇺🇸 英文 | 🇹🇷 土耳其文

🎉 v0.17.0 新特性：MCP 工具參數轉換修復 + 100% 測試成功！查看更新內容

特性 • 安裝 • 使用方法 • 文檔 • 貢獻代碼

🚀 快速開始

Gorev 是一個用 Go 語言編寫的強大的 模型上下文協議（MCP） 服務器，它為所有與 MCP 兼容的 AI 編輯器（如 Claude Desktop、VS Code、Windsurf、Cursor、Zed 等）提供任務管理功能。以下是快速啟動的步驟：

啟動守護進程

# 在後臺啟動守護進程
gorev daemon --detach

# 檢查守護進程狀態
curl http://localhost:5082/api/health

# 自動打開 Web UI
open http://localhost:5082

AI 助手示例命令

"創建新任務：編寫 API 文檔"
"列出緊急任務"
"顯示標記為 bug 的任務"
"將 Mobile App v2 項目設置為活動項目"
"創建用於衝刺規劃的新項目"
"將任務 #5 標記為已完成"
"使用功能請求模板創建新任務"
"開始監視項目文件"
"啟用文件更改時的自動狀態轉換"
"顯示監視列表"
"向文件監視器添加 git 忽略規則"

💡 使用建議：這些命令適用於 Claude、VS Code Copilot、Windsurf AI、Cursor 等與 MCP 兼容的 AI 助手。

✨ 主要特性

📝 任務管理

• 智能任務創建：支持使用自然語言命令創建任務。
• Markdown 支持：可對任務描述進行豐富的格式設置。
• 狀態管理：支持任務狀態從“待辦”到“進行中”再到“已完成”的轉換。
• 優先級設置：提供低、中、高三個優先級級別。
• 靈活編輯：可更新任務的所有屬性。

📁 項目組織

• 分層結構：支持將任務分組到項目下。
• 活動項目系統：可通過默認項目進行快速操作。
• 基於項目的報告：提供詳細的項目統計信息。
• 多項目支持：可創建無限數量的項目。

🔗 高級功能

• 📅 截止日期跟蹤：支持管理截止日期並篩選緊急任務。
• 🏷️ 標籤系統：支持多標籤分類。
• 🔄 任務依賴：實現任務間的自動化。
• 📋 預製模板：提供錯誤報告、功能請求等多種模板。
• 🔍 高級篩選：支持基於狀態、標籤、日期等條件進行查詢。
• 🌳 子任務層次結構：支持無限深度的任務樹結構。
• 📊 進度跟蹤：在父任務中顯示子任務的完成百分比。
• 📁 文件系統監視器：監控文件更改並自動轉換任務狀態。
• 🔔 自動狀態更新：文件更改時自動將任務狀態從“待辦”轉換為“進行中”。
• ⚙️ 配置管理：支持自定義忽略模式和監視規則。

🤖 AI 集成

• 自然語言處理：可通過與 AI 助手對話進行任務管理。
• 多編輯器支持：支持 Claude、VS Code、Windsurf、Cursor、Zed 等多種編輯器。
• 上下文理解：智能解釋命令。
• MCP 標準：與所有兼容 MCP 的工具兼容。

🎨 VS Code 擴展特性（可選）

• 雙語支持：提供土耳其語和英語界面（v0.5.0+）🌍。
• TreeView 面板：顯示任務、項目和模板列表。
• 可視化界面：提供點擊即用的操作體驗。
• 狀態欄：顯示即時狀態信息。
• 命令面板：可通過快捷鍵（Ctrl+Shift+G）快速訪問。
• 顏色編碼：根據優先級進行可視化區分。
• 上下文菜單：支持右鍵操作。
• 自動語言檢測：根據 VS Code 的語言設置自動切換 UI 語言。
• 從市場下載 🚀

🌐 Web UI 特性（v0.16.0 新增）

• 現代瀏覽器界面：無需 IDE，可在任何瀏覽器中使用。
• 任務卡片：以豐富的方式展示任務元數據。
• 子任務層次結構：支持展開和摺疊嵌套任務。
• 依賴徽章：直觀顯示任務依賴關係。
• 項目組織：通過側邊欄導航並顯示任務數量。
• 基於模板的創建：通過嚮導創建結構化任務。
• 即時更新：使用 React Query 實現自動同步。
• 響應式設計：支持在桌面和移動設備上使用。
• 🌍 語言切換器：可在土耳其語和英語之間切換，與 MCP 服務器同步。
• 快速操作：支持編輯、刪除和更新任務狀態。
• REST API 後端：基於 Fiber 框架的高性能 API 服務器。
• 🚀 無需安裝：運行 npx @mehmetsenol/gorev-mcp-server serve 即可使用！
• 嵌入式 UI：集成在 Go 二進制文件中，無需單獨設置。
• 訪問地址：http://localhost:5082（默認端口）

📦 安裝指南

🚀 NPM 快速設置（推薦！）

⚠️ Windows 用戶注意：NPM 需要安裝 Node.js。請從 Node.js 官網 下載並安裝，安裝完成後重啟系統。

全局安裝

npm install -g @mehmetsenol/gorev-mcp-server

或者直接使用 NPX（無需安裝）：

npx @mehmetsenol/gorev-mcp-server serve

MCP 客戶端配置

對於 Claude Desktop：

// Windows: %APPDATA%/Claude/claude_desktop_config.json
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}
// 注意：首次連接時守護進程會自動啟動，無需手動設置！

對於 Kilo Code（VS Code 擴展）：

// .kilocode/mcp.json (工作區根目錄)
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}

對於 Cursor：

// .cursor/mcp.json (工作區根目錄)
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}

📚 更多示例：MCP 配置指南

🔧 Windows NPX 故障排除

如果遇到 ENOENT: spawn npx 錯誤，請按以下步驟操作：

1. 檢查 Node.js 是否安裝：

node --version
npm --version
npx --version

2. 安裝 Node.js：

• 從 Node.js 官網 下載 LTS 版本。
• 安裝過程中勾選“添加到 PATH”選項。
• 安裝完成後重啟計算機。

3. 單獨安裝 NPX（如果需要）：

npm install -g npx

4. 檢查 PATH 環境變量：

echo %PATH%

確保 PATH 中包含 Node.js 的路徑（例如 C:\Program Files\nodejs\）。

🔧 傳統安裝（自動）

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | bash

# 指定版本
curl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | VERSION=v0.11.0 bash

🪟 Windows

# PowerShell（無需管理員權限）
irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex

# 或者指定版本：
$env:VERSION="v0.11.0"; irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex

💻 VS Code 擴展（可選）

選項 1：Gorev VS Code 擴展（推薦） 從 VS Code 市場 安裝：

code --install-extension mehmetsenol.gorev-vscode

💻 使用示例

基礎用法

通過 AI 助手使用自然語言命令進行任務管理，例如：

"創建新任務：編寫 API 文檔"

高級用法

使用 CLI 命令進行更復雜的操作，例如：

# 守護進程管理（推薦）
gorev daemon --detach        # 在後臺啟動守護進程
gorev daemon-status          # 檢查守護進程狀態
gorev daemon-stop            # 停止運行的守護進程

# 開發/測試（前臺模式）
gorev serve                  # 正常模式
gorev serve --debug          # 調試模式
gorev serve --port 8080      # 指定不同的端口

# 任務操作
gorev task list              # 列出任務
gorev task create            # 創建新任務
gorev task show <id>         # 查看任務詳情

# 項目操作
gorev project list           # 列出項目
gorev project create         # 創建新項目

# 其他
gorev version                # 查看版本信息
gorev help                 # 查看幫助信息

📚 詳細文檔

詳細文檔請參考 docs/ 文件夾：

入門指南

• 🚀 快速開始指南 - 10 分鐘內上手
• 📦 安裝指南 - 特定平臺的安裝說明
• 🆘 故障排除指南 - 常見問題及解決方案
• 🔄 遷移指南（v0.15→v0.16） - 從 v0.15 升級

特性說明

• 🌐 Web UI 指南 - 嵌入式 React 界面文檔
• 🗂️ 多工作區支持 - 管理多個項目
• 📋 模板系統 - 結構化任務創建
• 🤖 AI 上下文管理 - AI 助手集成

參考文檔

• 🛠️ MCP 工具參考 - 24 個優化後的 MCP 工具的完整參考（從 45 個統一而來）
• 🔧 MCP 配置示例 - IDE 設置指南
• 📖 使用指南 - 詳細的使用示例
• 🎨 VS Code 擴展 - 擴展文檔

開發文檔

• 🏗️ 系統架構 - 技術細節
• 💻 貢獻指南 - 如何貢獻代碼
• 🗺️ 路線圖 - 開發路線圖和未來計劃
• 📚 開發歷史 - 完整的項目歷史

AI 助手文檔

• 🌍 CLAUDE.en.md - 英文 AI 助手指南
• 🤖 CLAUDE.md - 土耳其文 AI 助手指南
• 📋 MCP 工具參考 - 詳細的 MCP 工具文檔
• 📚 開發歷史 - 完整的項目歷史

🔧 技術細節

三模塊架構

1. gorev-mcpserver - 用 Go 編寫的 MCP 服務器（核心組件）
   • 嵌入式 Web UI 🌐 - 二進制文件中嵌入的 React 界面（v0.16.0 新增！）
   • REST API 服務器（Fiber 框架）
   • 支持 MCP 協議
2. gorev-vscode - VS Code 擴展（可選的可視化界面）
3. gorev-web - React + TypeScript 源代碼（開發中）

由於支持 MCP 協議，你可以從任何與 MCP 兼容的編輯器連接到服務器。首次進行 MCP 連接時，守護進程會自動啟動，Web UI 可通過 http://localhost:5082 訪問。VS Code 擴展提供了豐富的 IDE 集成體驗，並自動管理守護進程。

守護進程架構（v0.16.0+）

Gorev 作為 後臺守護進程 運行，具有以下關鍵優勢：

核心特性

• 單實例管理：鎖文件 (~/.gorev-daemon/.lock) 防止端口衝突。
• 多客戶端支持：多個 MCP 客戶端（Claude、VS Code、Windsurf、Cursor）可以同時連接。
• 自動啟動：VS Code 擴展會自動檢測並啟動守護進程（v0.16.2+）。
• 健康監控：通過 /api/health 端點即時獲取狀態。
• WebSocket 支持：即時任務更新事件（實驗性）。

架構組件

• 鎖文件：~/.gorev-daemon/.lock 包含 PID、端口、版本和守護進程 URL。
• REST API 服務器：為 VS Code 擴展提供 23 個端點（Fiber 框架）。
• MCP 代理：將標準輸入輸出的 MCP 協議請求轉發到內部處理程序。
• WebSocket 服務器：即時廣播任務更新事件。
• 工作區管理器：支持多工作區，使用基於 SHA256 的 ID。

VS Code 集成

擴展會自動管理守護進程的生命週期：

1. 激活時，檢查守護進程是否正在運行（讀取鎖文件）。
2. 如果守護進程未運行，則啟動它。
3. 連接到 REST API 進行所有操作。
4. 可選：在擴展停用（如果是由擴展啟動的守護進程）時關閉守護進程。

詳細的技術規格請參考 守護進程架構文檔。

架構圖

graph TB
    subgraph "外部客戶端"
        Claude[Claude Desktop/Code]
        VSCode[VS Code Extension]
        Cursor[Cursor IDE]
        Windsurf[Windsurf]
    end

    subgraph "Gorev 守護進程 (端口 5082)"
        Lock[Lock File<br/>~/.gorev-daemon/.lock]

        subgraph "協議層"
            MCP[MCP Proxy<br/>stdio]
            REST[REST API<br/>Fiber - 23 個端點]
            WS[WebSocket<br/>即時事件]
        end

        Handler[MCP 處理程序<br/>24 個統一工具]

        subgraph "存儲"
            DB[(SQLite 數據庫<br/>.gorev/gorev.db)]
        end

        WebUI[嵌入式 Web UI<br/>React + TypeScript]
    end

    Claude -->|MCP/stdio| MCP
    VSCode -->|REST/HTTP| REST
    Cursor -->|MCP/stdio| MCP
    Windsurf -->|MCP/stdio| MCP

    MCP --> Handler
    REST --> Handler
    WS -.->|廣播| VSCode

    Handler --> DB

    REST --> WebUI

    Lock -.->|管理| MCP
    Lock -.->|管理| REST

    style Claude fill:#f9f,stroke:#333
    style VSCode fill:#9cf,stroke:#333
    style Cursor fill:#fc9,stroke:#333
    style Windsurf fill:#9fc,stroke:#333
    style Handler fill:#ff9,stroke:#333
    style DB fill:#9f9,stroke:#333

🎉 v0.17.0 有哪些新特性

🔧 MCP 工具參數轉換修復（2025 年 10 月 6 日）

• gorev_bulk - 所有 3 個操作現在都完全正常工作：
  • update 操作：正確將 {ids: [], data: {}} 轉換為 {updates: [{id, ...fields}]}。
  • transition 操作：支持 status 和 yeni_durum 兩種參數名，提高靈活性。
  • tag 操作：支持 operation 和 tag_operation 兩種參數名。
  • 測試結果：成功率 100%（生產環境中 5/5 個操作通過）。
• gorev_guncelle - 擴展為支持多個字段更新：
  • 可以同時更新 status（狀態）、priority（優先級）或兩者。
  • 驗證時至少需要一個參數。
  • 與現有代碼向後兼容。
• gorev_search（高級模式） - 增加了智能查詢解析：
  • 示例："durum:devam_ediyor oncelik:yuksek tags:frontend"
  • 自動從自然語言查詢中提取過濾器。
  • 支持使用空格分隔的鍵值對進行多過濾器查詢。
  • 與現有過濾器參數無縫配合。
• VS Code 樹視圖 - 依賴指示器現在可見：
  • 🔒（阻塞）、🔓（未阻塞）、🔗（依賴項）圖標顯示正確。
  • 修復了 JSON 序列化問題（從依賴計數器中移除了 omitempty）。
  • 所有依賴關係現在都可以在樹結構中可見。

驗證：Kilocode AI 綜合測試報告確認成功率為 100%。

🐛 之前的更新（v0.16.2 - 2025 年 10 月 5 日）

• NPM 二進制更新修復：修復了 NPM 包升級時保留舊二進制文件的關鍵 bug。
  • 從 v0.16.1 或更早版本升級的用戶之前會停留在 v0.15.24（2025 年 9 月）。
  • 包大小從 78.4 MB 減少到 6.9 KB（現在二進制文件總是從 GitHub 下載）。
  • 所有用戶現在都可以獲得最新功能（REST API、Web UI、VS Code 自動啟動）。
• VS Code 自動啟動：擴展現在會自動檢測並啟動守護進程。
  • 無需手動命令 - 通過檢測鎖文件自動啟動守護進程。
  • 檢查守護進程是否正在運行（~/.gorev-daemon/.lock），如果未運行則啟動。
  • 正確配置數據庫路徑（workspace/.gorev/gorev.db）。
  • 所有 MCP 客戶端（Claude、Cursor、Windsurf）共享守護進程。

🌐 嵌入式 Web UI（v0.16.0）

• 零配置：現代的 React 界面集成在 Go 二進制文件中。
• 即時訪問：自動通過 http://localhost:5082 可用。
• 完整功能：支持任務、項目、模板、子任務和依賴關係管理。
• 語言同步：土耳其語/英語切換器與 MCP 服務器同步。
• 無需單獨安裝：只需運行 npx @mehmetsenol/gorev-mcp-server serve 即可開始使用！

🗂️ 多工作區支持（v0.16.0）

• 隔離工作區：每個項目文件夾都有自己的任務數據庫。
• 工作區切換器：在 Web UI 中無縫切換工作區。
• 自動檢測：自動檢測當前文件夾中的 .gorev/ 目錄。
• SHA256 ID：安全的工作區標識。
• VS Code 集成：擴展在激活時自動註冊工作區。

🔌 REST API 遷移

• 23 個端點：完整的基於 Fiber 的 REST API。
• VS Code 擴展：從 MCP 遷移到 REST API 以提高性能。
• 類型安全：100% TypeScript，無解析錯誤。
• 更快：直接的 HTTP 調用，而不是標準輸入輸出 + Markdown 解析。
• 向後兼容：仍然完全支持 MCP 協議。

🏷️ 模板別名

• 快速命令：可以使用 bug、feature、research 代替模板 ID。
• 一致性：所有工作區使用相同的別名。
• 無需查找 UUID：使用人類可讀的模板標識符。
• 文檔：完整指南請參考 MCP 配置示例。

📦 NPM 包

• 包名：@mehmetsenol/gorev-mcp-server
• 全局安裝：npm install -g @mehmetsenol/gorev-mcp-server
• NPX 即用：npx @mehmetsenol/gorev-mcp-server serve 可立即使用。
• 跨平臺：支持 Windows、macOS 和 Linux。

📄 許可證

本項目採用 MIT 許可證 授權。

🚨 重大變更：模板要求

從 v0.10.0 開始，gorev_olustur 工具已被移除。現在所有任務創建都必須使用模板系統，以獲得更好的結構和一致性。

遷移指南

之前（v0.9.x 及更早版本）：

創建新任務：修復登錄 bug

之後（v0.10.0+）：

使用 bug-report 模板創建：修復登錄 bug

可用模板：

• bug-report - 錯誤報告和修復
• feature - 新功能和改進
• task - 一般任務和活動
• meeting - 會議規劃和記錄
• research - 研究和調查任務

更多詳細信息，請參考 MCP 工具文檔。

🤝 社區

• 📦 GitHub 發佈
• 🐛 問題跟蹤
• 💬 討論區
• 📖 Wiki