devlake-mcp 0.4.1__py3-none-any.whl

devlake_mcp/version_utils.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+版本检测工具模块
+
+提供以下功能：
+1. 获取 devlake-mcp 版本号
+2. 检测 Claude Code 版本
+3. 检测 Cursor 版本
+4. 自动检测平台类型和版本信息
+"""
+
+import os
+import logging
+import subprocess
+from typing import Optional, Dict, Union
+
+from .enums import IDEType
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# DevLake MCP 版本检测
+# ============================================================================
+
+def get_devlake_mcp_version() -> str:
+    """
+    获取 devlake-mcp 包的版本号
+
+    Returns:
+        版本号字符串，如 "0.3.1"，失败返回 "unknown"
+    """
+    try:
+        from devlake_mcp import __version__
+        return __version__
+    except Exception as e:
+        logger.warning(f'获取 devlake-mcp 版本失败: {e}')
+        return 'unknown'
+
+
+# ============================================================================
+# Claude Code 版本检测
+# ============================================================================
+
+def get_claude_code_version() -> Optional[str]:
+    """
+    检测 Claude Code 版本号
+
+    尝试以下方法：
+    1. 从环境变量 CLAUDE_CODE_VERSION 读取
+    2. 执行 claude --version 命令
+
+    Returns:
+        版本号字符串，如 "0.1.5"，未检测到返回 None
+    """
+    # 方法1: 环境变量（最快）
+    version = os.getenv('CLAUDE_CODE_VERSION')
+    if version:
+        logger.debug(f'从环境变量检测到 Claude Code 版本: {version}')
+        return version
+
+    # 方法2: 执行 claude --version 命令
+    try:
+        result = subprocess.run(
+            ['claude', '--version'],
+            capture_output=True,
+            text=True,
+            timeout=2
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            # 直接使用命令输出，不做任何解析
+            version = result.stdout.strip()
+            logger.debug(f'从命令行检测到 Claude Code 版本: {version}')
+            return version
+    except Exception as e:
+        logger.debug(f'执行 claude --version 失败: {e}')
+
+    logger.debug('未能检测到 Claude Code 版本')
+    return None
+
+
+# ============================================================================
+# Cursor 版本检测
+# ============================================================================
+
+def get_cursor_version() -> Optional[str]:
+    """
+    检测 Cursor 版本号
+
+    尝试以下方法：
+    1. 从环境变量 CURSOR_VERSION 读取
+    2. 执行 cursor-agent -v 命令
+
+    Returns:
+        版本号字符串，如 "0.40.1"，未检测到返回 None
+    """
+    # 方法1: 环境变量
+    version = os.getenv('CURSOR_VERSION')
+    if version:
+        logger.debug(f'从环境变量检测到 Cursor 版本: {version}')
+        return version
+
+    # 方法2: 执行 cursor-agent -v 命令
+    try:
+        result = subprocess.run(
+            ['cursor-agent', '-v'],
+            capture_output=True,
+            text=True,
+            timeout=2
+        )
+        if result.returncode == 0:
+            # 提取版本号
+            output = result.stdout.strip()
+            # 可能的输出格式：0.40.1 或 cursor-agent version 0.40.1
+            parts = output.split()
+            version = parts[-1]  # 取最后一个单词作为版本号
+            logger.debug(f'从命令行检测到 Cursor 版本: {version}')
+            return version
+    except Exception as e:
+        logger.debug(f'执行 cursor-agent -v 失败: {e}')
+
+    logger.debug('未能检测到 Cursor 版本')
+    return None
+
+
+# ============================================================================
+# 统一检测接口
+# ============================================================================
+
+def detect_platform_info(ide_type: IDEType) -> Dict[str, Optional[str]]:
+    """
+    检测平台类型和版本信息
+
+    Args:
+        ide_type: IDE 类型枚举
+                 应该从调用 hook 的上下文中获取，因为不同 IDE 使用不同的 hook
+
+    Returns:
+        包含以下字段的字典：
+        - devlake_mcp_version: DevLake MCP 版本（字符串）
+        - ide_version: IDE 版本号（可能为 None）
+        - data_source: 数据来源（固定为 'hook'）
+
+    注意：
+        - 不返回 ide_type，因为调用方已经知道（避免字段重复）
+        - 因为 Claude Code 和 Cursor 使用不同的 hook，所以调用时就知道平台类型
+        - 不需要通过环境变量、进程名或目录来检测平台
+    """
+    # 获取字符串值并规范化
+    ide_type_str = ide_type.value
+    normalized_ide_type = ide_type_str.lower()
+
+    result = {
+        'devlake_mcp_version': get_devlake_mcp_version(),
+        'ide_version': None,
+        'data_source': 'hook'
+    }
+
+    # 根据 IDE 类型获取版本
+    if normalized_ide_type == IDEType.CLAUDE_CODE.value:
+        result['ide_version'] = get_claude_code_version()
+    elif normalized_ide_type == IDEType.CURSOR.value:
+        result['ide_version'] = get_cursor_version()
+    # qoder 和其他平台：暂不支持版本检测
+
+    logger.info(
+        f'平台检测完成: '
+        f'ide_type={ide_type_str}, '
+        f'devlake-mcp={result["devlake_mcp_version"]}, '
+        f'ide_version={result["ide_version"] or "unknown"}'
+    )
+
+    return result

devlake_mcp-0.4.1.dist-info/METADATA

@@ -0,0 +1,541 @@
+Metadata-Version: 2.4
+Name: devlake-mcp
+Version: 0.4.1
+Summary: AI programming data collection tool - supports Hooks (Claude Code/Cursor) and MCP server modes
+Author-email: wangzhong <wangzhong@g7.com.cn>
+License-Expression: MIT
+Project-URL: Homepage, https://git.chinawayltd.com/engineering-efficiency/devlake-mcp
+Project-URL: Repository, https://git.chinawayltd.com/engineering-efficiency/devlake-mcp
+Project-URL: Issues, https://git.chinawayltd.com/engineering-efficiency/devlake-mcp
+Keywords: mcp,devlake,model-context-protocol,ai,llm,claude-code,cursor,hooks,ai-programming,code-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: mcp
+Requires-Dist: fastmcp~=2.13.0; python_version >= "3.10" and extra == "mcp"
+Provides-Extra: full
+Requires-Dist: devlake-mcp[mcp]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
+Requires-Dist: responses>=0.24.0; extra == "dev"
+Requires-Dist: freezegun>=1.4.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# DevLake MCP
+
+DevLake MCP 是一个 AI 编程数据采集工具，支持两种工作模式：
+
+- **🔌 Hooks 模式** - 通过 IDE Hooks 自动采集 AI 编程数据（推荐日常使用）
+- **🤖 MCP 模式** - 作为 MCP 服务器，让 AI 助手主动调用工具记录数据
+
+## Python 版本要求
+
+| Python 版本 | Hooks 模式 | MCP Server 模式 |
+|------------|-----------|----------------|
+| 3.9.x      | ✅ 支持   | ❌ 不支持      |
+| 3.10+      | ✅ 支持   | ✅ 支持        |
+
+**推荐使用 Python 3.10 或更高版本以获得完整功能支持。**
+
+## 快速安装
+
+### 基础安装（Python 3.9+，仅 Hooks 模式）
+
+```bash
+# 使用 pipx 安装（推荐）
+pipx install devlake-mcp
+
+# 或使用 pip
+pip install devlake-mcp
+```
+
+### 完整安装（Python 3.10+，Hooks + MCP Server）
+
+```bash
+# 使用 pipx 安装（推荐）
+pipx install "devlake-mcp[mcp]"
+
+# 或使用 pip
+pip install "devlake-mcp[mcp]"
+```
+
+### 检查安装
+
+```bash
+# 查看版本号
+devlake-mcp --version
+# 输出: devlake-mcp 0.3.4
+
+# 查看详细的版本和功能支持状态
+devlake-mcp info
+```
+
+`devlake-mcp info` 输出示例：
+```
+============================================================
+DevLake MCP - 版本信息
+============================================================
+DevLake MCP: v0.3.4
+Python: 3.10.19
+
+功能支持:
+  - Hooks 模式: ✓
+  - MCP Server: ✓ (FastMCP 2.13.0.2)
+============================================================
+```
+
+## 环境配置
+
+```bash
+# 配置 DevLake API 地址（可选，默认使用测试环境）
+export DEVLAKE_BASE_URL="http://devlake.test.chinawayltd.com"
+export DEVLAKE_TIMEOUT=5
+
+# 确保 Git 配置正确（必需）
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+```
+
+# 日志配置（可选）
+export DEVLAKE_MCP_LOGGING_ENABLED=true  # 是否启用日志（默认 true）
+export DEVLAKE_MCP_LOG_LEVEL=INFO        # 日志级别：DEBUG/INFO/WARNING/ERROR/CRITICAL（默认 INFO）
+export DEVLAKE_MCP_CONSOLE_LOG=false     # 是否输出到控制台（默认 false，仅开发调试时启用）
+
+---
+
+## 🔌 模式一：Hooks 自动采集（推荐）
+
+Hooks 模式通过 IDE 的 Hooks 机制**自动**采集 AI 编程数据，无需 AI 主动调用工具，适合日常开发使用。
+
+### Claude Code Hooks
+
+#### 一键初始化
+
+```bash
+# 自动配置 .claude/settings.json
+# 如果已有配置，将智能合并 hooks 部分（保留您的现有配置）
+devlake-mcp init
+
+# 强制完全覆盖已有配置（不推荐，将丢失现有配置）
+devlake-mcp init --force
+```
+
+**智能合并说明**：
+- ✅ 自动检测现有 settings.json 配置
+- ✅ 仅添加或更新 `hooks` 部分
+- ✅ 完全保留您的其他配置（如 `mcpServers`、`permissions`、`statusLine` 等）
+- ✅ 如果 DevLake hooks 已配置，则跳过无需更新
+- ⚠️  使用 `--force` 选项会完全覆盖配置文件，谨慎使用
+
+#### 支持的 Hooks
+
+| Hook | 触发时机 | 功能 |
+|------|---------|------|
+| **SessionStart** | 会话启动 | 创建 session 记录 |
+| **UserPromptSubmit** | 用户提交 prompt | 记录用户输入 |
+| **PreToolUse** | 工具使用前 | 记录文件变更前状态 |
+| **PostToolUse** | 工具使用后 | 上传文件变更（diff） |
+| **Stop** | AI 循环停止 | 更新会话统计 |
+| **SessionEnd** | 会话结束 | 上传完整会话数据 |
+
+#### 技术特点
+
+- ✅ 使用 Claude Code 原生 `session_id`，无需额外管理
+- ✅ 自动检测会话切换和超时（30 分钟）
+- ✅ 异步上传，不阻塞 IDE 操作
+- ✅ 失败自动加入重试队列
+
+#### 配置示例
+
+初始化后会在 `.claude/settings.json` 中生成以下配置：
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -m devlake_mcp.hooks.session_start",
+        "timeout": 5
+      }]
+    }],
+    "UserPromptSubmit": [{
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -m devlake_mcp.hooks.user_prompt_submit",
+        "timeout": 5
+      }]
+    }],
+    "PreToolUse": [{
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -m devlake_mcp.hooks.pre_tool_use",
+        "timeout": 5
+      }]
+    }],
+    "PostToolUse": [{
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -m devlake_mcp.hooks.post_tool_use",
+        "timeout": 10
+      }]
+    }],
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -m devlake_mcp.hooks.stop",
+        "timeout": 5
+      }]
+    }],
+    "SessionEnd": [{
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -m devlake_mcp.hooks.session_end",
+        "timeout": 10
+      }]
+    }]
+  }
+}
+```
+
+---
+
+### Cursor Hooks
+
+#### 一键初始化
+
+```bash
+# 自动配置 Cursor hooks
+devlake-mcp init-cursor
+
+# 强制覆盖已有配置
+devlake-mcp init-cursor --force
+```
+
+#### 支持的 Hooks
+
+| Hook | 触发时机 | 功能 |
+|------|---------|------|
+| **beforeSubmitPrompt** | 用户提交 prompt 前 | 记录用户输入 |
+| **beforeReadFile** | 读取文件前 | 记录文件访问 |
+| **beforeShellExecution** | 执行 Shell 前 | 记录命令信息 |
+| **afterShellExecution** | Shell 执行后 | 检测命令产生的文件变更 |
+| **afterFileEdit** | 文件编辑后 | 上传文件编辑变更 |
+| **afterAgentResponse** | AI 回复后 | 记录对话内容 |
+| **stop** | 会话结束 | 上传会话统计 |
+
+#### 技术特点
+
+- ✅ 使用 Cursor 原生 `conversation_id` 作为 session_id
+- ✅ `generation_id` 关联同一次 AI 生成的多个文件变更
+- ✅ 自动检测 vim/nano/echo>/cp/mv 等文件操作命令
+- ✅ 智能 diff 算法计算文件变更
+- ✅ 与 Claude Code 完全兼容的数据格式
+- ✅ 精确的工作目录定位（workspace_roots）
+
+#### 详细文档
+
+查看 [CURSOR_HOOKS.md](CURSOR_HOOKS.md) 了解完整配置和使用指南。
+
+---
+
+### Hooks 模式对比
+
+| 特性 | Claude Code | Cursor |
+|------|-------------|--------|
+| Session 管理 | 30分钟超时机制 | 对话生命周期管理 |
+| 文件变更追踪 | ✅ | ✅ |
+| Shell 命令检测 | ❌ | ✅ |
+| 变更关联追踪 | 单个变更 | ✅ generation_id 关联 |
+| 工作目录定位 | 手动推断 | ✅ workspace_roots |
+| 数据格式 | 原生格式 | 完全兼容 Claude Code |
+
+---
+
+## 🤖 模式二：MCP 服务器模式
+
+MCP 模式将 DevLake 作为 [Model Context Protocol](https://modelcontextprotocol.io) 服务器运行，基于 [FastMCP](https://gofastmcp.com) 框架，让 AI 助手可以**主动调用工具**记录数据。
+
+### 配置方式
+
+#### 方式 1：使用 Claude CLI（推荐）
+
+```bash
+claude mcp add devlake-mcp devlake-mcp
+```
+
+#### 方式 2：手动配置
+
+编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或相应配置文件：
+
+```json
+{
+  "mcpServers": {
+    "devlake-mcp": {
+      "command": "devlake-mcp"
+    }
+  }
+}
+```
+
+配置完成后重启 Claude Desktop。
+
+### 可用工具
+
+MCP 模式提供 3 个核心工具，AI 助手可以主动调用：
+
+#### 1. `record_session`
+
+**功能**：记录 AI 会话的元数据和统计信息
+
+**参数**：
+- `session_id` (string, 可选)：会话 ID，不提供则自动生成 UUID
+- `metadata` (dict, 可选)：会话元数据
+  - `user_intent`：用户意图描述
+  - `model`：模型名称（如 "claude-sonnet-4-5"）
+  - `ide`：IDE 类型（如 "cursor", "claude-code"）
+  - `project_path`：项目路径
+
+**返回示例**：
+```json
+{
+  "success": true,
+  "session_id": "uuid-xxx",
+  "timestamp": "2025-01-07T10:00:00Z",
+  "git_info": {
+    "git_repo_path": "yourorg/devlake",
+    "git_branch": "main",
+    "git_author": "Your Name"
+  }
+}
+```
+
+**使用示例**：
+```
+调用 record_session 工具，metadata 设置为 {"ide": "cursor", "model": "claude-sonnet-4-5"}
+```
+
+---
+
+#### 2. `before_edit_file`
+
+**功能**：在文件变更前调用，记录文件的当前状态（快照）
+
+**参数**：
+- `session_id` (string, 必需)：会话唯一标识
+- `file_paths` (list[string], 必需)：即将变更的文件绝对路径列表
+
+**返回示例**：
+```json
+{
+  "success": true,
+  "session_id": "session-123",
+  "files_snapshot": {
+    "/path/to/file.py": {
+      "exists": true,
+      "line_count": 100,
+      "size": 2048
+    }
+  }
+}
+```
+
+**使用示例**：
+```
+调用 before_edit_file 工具，session_id 为 "session-123"，file_paths 为 ["/path/to/file.py"]
+```
+
+---
+
+#### 3. `after_edit_file`
+
+**功能**：在文件变更后调用，对比差异并上传变更数据到 DevLake API
+
+**参数**：
+- `session_id` (string, 必需)：会话唯一标识（与 before_edit_file 一致）
+- `file_paths` (list[string], 必需)：已变更的文件绝对路径列表
+
+**返回示例**：
+```json
+{
+  "success": true,
+  "session_id": "session-123",
+  "uploaded_count": 1,
+  "changes": [
+    {
+      "file_path": "src/main.py",
+      "change_type": "edit",
+      "file_type": "py"
+    }
+  ]
+}
+```
+
+**工作流程**：
+```
+1. before_edit_file() - 记录文件变更前状态
+2. [AI 执行文件变更操作]
+3. after_edit_file() - 对比差异并上传
+```
+
+**使用示例**：
+```
+调用 after_edit_file 工具，session_id 为 "session-123"，file_paths 为 ["/path/to/file.py"]
+```
+
+---
+
+### MCP 模式特点
+
+- ✅ **AI 主动控制**：由 AI 决定何时记录数据
+- ✅ **精确记录时机**：在最合适的时间点调用工具
+- ✅ **完整的 before/after 对比**：准确的文件变更 diff
+- ✅ **跨 IDE 支持**：适用于任何支持 MCP 的 AI 助手
+- ✅ **手动 Session 管理**：AI 自行管理会话生命周期
+
+---
+
+## 失败重试机制
+
+DevLake MCP 内置智能失败重试队列，确保数据不会因网络问题或临时故障丢失。
+
+### 工作原理
+
+当 API 调用失败时，失败记录自动保存到本地队列，按**指数退避策略**自动重试：
+
+| 重试次数 | 等待时间 |
+|---------|---------|
+| 第 1 次 | 1 分钟 |
+| 第 2 次 | 5 分钟 |
+| 第 3 次 | 15 分钟 |
+| 第 4 次 | 60 分钟 |
+| 第 5 次 | 4 小时 |
+
+### 队列管理命令
+
+```bash
+# 查看失败队列状态和统计
+devlake-mcp queue-status
+
+# 手动触发重试（不等待自动重试时间）
+devlake-mcp retry
+
+# 清理过期的失败记录（默认保留 7 天）
+devlake-mcp queue-clean
+```
+
+### 配置选项
+
+通过环境变量配置重试行为：
+
+```bash
+# 启用/禁用重试（默认 true）
+export DEVLAKE_RETRY_ENABLED=true
+
+# 最大重试次数（默认 5）
+export DEVLAKE_RETRY_MAX_ATTEMPTS=5
+
+# 失败记录保留天数（默认 7）
+export DEVLAKE_RETRY_CLEANUP_DAYS=7
+
+# Hook 执行时检查重试（默认 true）
+export DEVLAKE_RETRY_CHECK_ON_HOOK=true
+```
+
+### 自动重试
+
+当 `DEVLAKE_RETRY_CHECK_ON_HOOK=true` 时（默认），每次 Hook 执行时会自动检查并重试失败的记录（每次最多 3 条，避免阻塞）。
+
+如需禁用自动重试：
+```bash
+export DEVLAKE_RETRY_CHECK_ON_HOOK=false
+```
+
+然后使用 `devlake-mcp retry` 手动触发。
+
+---
+
+## CLI 命令总览
+
+```bash
+# MCP 服务器
+devlake-mcp                     # 启动 MCP 服务器
+
+# Hooks 初始化
+devlake-mcp init                # 初始化 Claude Code hooks
+devlake-mcp init --force        # 强制覆盖 Claude Code hooks
+devlake-mcp init-cursor         # 初始化 Cursor hooks
+devlake-mcp init-cursor --force # 强制覆盖 Cursor hooks
+
+# 失败队列管理
+devlake-mcp queue-status        # 查看失败队列状态
+devlake-mcp retry               # 手动触发重试
+devlake-mcp queue-clean         # 清理过期记录
+
+# 版本信息
+devlake-mcp --version           # 显示版本号
+devlake-mcp info                # 显示详细的版本和功能支持信息
+devlake-mcp --help              # 显示帮助信息
+```
+
+---
+
+## 使用建议
+
+### 选择合适的模式
+
+| 场景 | 推荐模式 | 理由 |
+|------|---------|------|
+| 日常开发 | **Hooks 模式** | 自动采集，无需关注 |
+| 精确控制记录时机 | **MCP 模式** | AI 主动决定何时记录 |
+| Claude Code | **Hooks 模式** | 原生集成，体验最佳 |
+| Cursor | **Hooks 模式** | 专门优化，功能最全 |
+| Claude Desktop | **MCP 模式** | 标准 MCP 协议支持 |
+
+### 两种模式可以共存
+
+Hooks 模式和 MCP 模式可以同时启用：
+- Hooks 模式负责自动采集日常数据
+- MCP 模式让 AI 在特殊场景下主动记录
+
+---
+
+## 相关资源
+
+- [Model Context Protocol 官方文档](https://modelcontextprotocol.io)
+- [FastMCP 官方文档](https://gofastmcp.com)
+- [FastMCP GitHub](https://github.com/jlowin/fastmcp)
+- [Claude Desktop](https://claude.ai/download)
+- [Cursor 编辑器](https://cursor.sh)
+- [Cursor Hooks 详细文档](CURSOR_HOOKS.md)
+
+---
+
+## Git 配置要求
+
+工具会自动从 Git 配置读取用户信息，请确保已配置：
+
+```bash
+# 配置 Git 用户信息
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+
+# 配置仓库远程地址
+git remote add origin <repository-url>
+```