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