devlake-mcp 0.4.1__py3-none-any.whl

devlake_mcp/hooks/hook_utils.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Claude Code Hooks 公共工具模块
+
+提供跨 hooks 脚本的通用功能：
+- 错误日志记录
+- 本地队列保存（降级方案）
+- 统一的 logging 配置
+- 异步执行包装
+
+注意：临时目录等通用功能已移至 devlake_mcp.utils，避免重复代码
+"""
+
+import os
+import sys
+import json
+import logging
+from pathlib import Path
+from datetime import datetime
+from typing import Callable
+
+# 导入通用工具函数（避免代码重复）
+from devlake_mcp.utils import get_data_dir, get_temp_file_path
+from devlake_mcp.constants import HOOK_LOG_DIR
+
+# 注意：hook_utils 是基础模块，不导入其他 hooks 模块以避免循环依赖
+
+
+# 模块级 logger（Python logging 有 lastResort 机制，无需手动配置）
+logger = logging.getLogger(__name__)
+
+
+def save_to_local_queue(queue_name: str, data: dict):
+    """
+    保存数据到本地队列（降级方案）
+
+    用于 API 上传失败时的备份，后续可通过定时脚本重试上传
+
+    Args:
+        queue_name: 队列名称（如 'failed_session_uploads'）
+        data: 要保存的数据字典
+
+    文件格式:
+        ~/.devlake/{queue_name}/{timestamp}.json
+    """
+    try:
+        queue_dir = get_data_dir(persistent=True) / queue_name
+        queue_dir.mkdir(parents=True, exist_ok=True)
+
+        # 使用时间戳作为文件名，确保唯一性
+        filename = f"{int(datetime.now().timestamp() * 1000)}.json"
+        queue_file = queue_dir / filename
+
+        with open(queue_file, 'w', encoding='utf-8') as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+    except Exception as e:
+        # 记录失败，不影响主流程（Python logging 会自动输出到 stderr）
+        logger.error(
+            f"Failed to save to local queue '{queue_name}': {e}",
+            exc_info=True
+        )
+
+
+def cleanup_old_files(directory: str, max_age_hours: int = 24):
+    """
+    清理指定目录中的过期文件
+
+    Args:
+        directory: 目录名称（相对于持久化数据目录）
+        max_age_hours: 最大保留时间（小时）
+
+    示例:
+        cleanup_old_files('failed_session_uploads', max_age_hours=168)  # 7天
+    """
+    try:
+        target_dir = get_data_dir(persistent=True) / directory
+        if not target_dir.exists():
+            return
+
+        now = datetime.now().timestamp()
+        max_age_seconds = max_age_hours * 3600
+
+        for file in target_dir.iterdir():
+            if file.is_file():
+                file_age = now - file.stat().st_mtime
+                if file_age > max_age_seconds:
+                    file.unlink()
+    except Exception as e:
+        # 记录失败，不影响主流程（Python logging 会自动输出到 stderr）
+        logger.error(
+            f"Failed to cleanup old files in '{directory}': {e}",
+            exc_info=True
+        )
+
+
+__all__ = ['save_to_local_queue', 'cleanup_old_files', 'run_async']
+
+
+def run_async(func: Callable):
+    """
+    异步执行装饰器，让 hook 立即返回，后台执行任务
+
+    原理（标准的双重 fork daemon 化）：
+    1. 第一次 fork：创建子进程，父进程立即退出
+    2. setsid()：子进程创建新会话，脱离控制终端
+    3. 第二次 fork：创建孙进程，第一个子进程退出
+    4. 孙进程（真正的 daemon）执行实际工作
+
+    为什么需要双重 fork？
+    - 单次 fork：子进程仍在父进程的会话中，可能被 Claude Code 等待
+    - setsid()：创建新会话，但子进程成为 session leader
+    - 第二次 fork：确保孙进程不是 session leader，完全独立
+
+    参考：Stevens "Advanced Programming in the UNIX Environment"
+
+    使用方法：
+        @run_async
+        def main():
+            # 你的 hook 逻辑
+            pass
+
+        if __name__ == '__main__':
+            main()
+
+    优点：
+    - hook 0 延迟，不阻塞 Claude 响应（即使 API 超时 10 秒）
+    - 完全脱离父进程会话，不会被等待
+    - API 调用慢或失败不影响用户体验
+
+    注意：
+    - 只在 Unix-like 系统（macOS/Linux）使用 fork
+    - Windows 会降级为同步执行（因为 fork 不可用）
+    """
+    def wrapper(*args, **kwargs):
+        # 检查是否支持 fork（Unix-like 系统）
+        if sys.platform == 'win32' or not hasattr(os, 'fork'):
+            # Windows 或不支持 fork 的系统，降级为同步执行
+            func(*args, **kwargs)
+            _check_and_retry_uploads()  # 同步模式下也检查重试
+            return
+
+        # === 第一次 fork ===
+        try:
+            pid = os.fork()
+        except OSError:
+            # fork 失败，降级为同步执行
+            func(*args, **kwargs)
+            _check_and_retry_uploads()
+            return
+
+        if pid > 0:
+            # 父进程：立即退出（返回给 Claude Code）
+            os._exit(0)
+
+        # === 第一个子进程 ===
+        try:
+            # 创建新会话，脱离控制终端
+            # 此时子进程成为 session leader
+            os.setsid()
+        except OSError:
+            # setsid 失败，退出
+            os._exit(1)
+
+        # === 第二次 fork ===
+        try:
+            pid = os.fork()
+        except OSError:
+            # fork 失败，退出
+            os._exit(1)
+
+        if pid > 0:
+            # 第一个子进程：退出
+            # 让孙进程被 init 进程接管
+            os._exit(0)
+
+        # === 孙进程（真正的 daemon）===
+        try:
+            # 1. 读取 stdin 内容（在关闭文件描述符之前）
+            from io import StringIO
+            try:
+                stdin_content = sys.stdin.read()
+            except Exception:
+                stdin_content = ''
+
+            # 2. 关闭并重定向标准文件描述符（关键！）
+            # 这是 daemon 化的必要步骤，确保 subprocess.run 不会等待
+            sys.stdout.flush()
+            sys.stderr.flush()
+
+            # 关闭标准输入/输出/错误的文件描述符
+            os.close(0)  # stdin
+            os.close(1)  # stdout
+            os.close(2)  # stderr
+
+            # 重新打开到 /dev/null 或日志文件
+            # stdin -> /dev/null
+            os.open('/dev/null', os.O_RDONLY)  # 返回 fd 0
+
+            # stdout 和 stderr -> 保留日志功能
+            # 注意：由于我们已经配置了 logging 到文件，这里重定向到 /dev/null 不影响日志
+            os.open('/dev/null', os.O_WRONLY)  # 返回 fd 1 (stdout)
+            os.open('/dev/null', os.O_WRONLY)  # 返回 fd 2 (stderr)
+
+            # 3. 用 StringIO 替换 Python 的 sys.stdin（让代码能正常读取）
+            sys.stdin = StringIO(stdin_content)
+
+            # 4. 执行主 hook 逻辑
+            func(*args, **kwargs)
+
+            # 5. 检查并重试失败的上传记录（非阻塞）
+            _check_and_retry_uploads()
+
+            # daemon 正常退出
+            os._exit(0)
+        except Exception:
+            # daemon 异常退出
+            os._exit(1)
+
+    return wrapper
+
+
+def _check_and_retry_uploads():
+    """
+    检查并重试失败的上传记录（内部函数）
+
+    说明：
+    - 每次 Hook 执行时自动调用
+    - 非阻塞，快速返回（默认最多重试3条记录）
+    - 静默失败，不影响主流程
+    """
+    try:
+        # 延迟导入，避免循环依赖
+        from devlake_mcp.retry_queue import retry_failed_uploads, get_retry_config
+
+        # 检查是否启用重试
+        config = get_retry_config()
+        if not config.get('check_on_hook', True):
+            return
+
+        # 执行重试（限制单次最多3条，避免阻塞）
+        retry_failed_uploads(max_parallel=3)
+
+    except Exception as e:
+        # 静默失败，不影响主流程
+        logger.debug(f"重试检查失败（不影响主流程）: {e}")

devlake_mcp/hooks/post_tool_use.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Claude Code Hooks: AI出码数据采集脚本（v1.5 重构版本）
+
+改进：
+- 添加统一的日志系统（参考 stop.py）
+- 添加异步执行，立即返回，不阻塞工具执行
+- 移除本地 diff 计算（改为云端计算）
+- 添加 gzip 压缩传输
+- 完整上传 before/after 内容（不截断）
+- 添加降级方案（API 失败时保存本地）
+- 跨平台临时目录支持（Windows/macOS/Linux）
+
+作者：Claude Code
+版本：v1.5
+日期：2025-01-04
+"""
+
+import json
+import logging
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+# 导入公共工具（使用包导入）
+from devlake_mcp.hooks.hook_utils import run_async
+from devlake_mcp.utils import get_temp_file_path, compress_content
+from devlake_mcp.git_utils import get_git_context_from_file
+from devlake_mcp.client import DevLakeClient
+from devlake_mcp.retry_queue import save_failed_upload
+from devlake_mcp.session_manager import check_and_switch_session
+from devlake_mcp.generation_manager import get_current_generation_id
+from devlake_mcp.logging_config import configure_logging, get_log_dir
+from devlake_mcp.constants import HOOK_LOG_DIR
+
+# 配置日志（启动时调用一次）
+configure_logging(log_dir=get_log_dir(HOOK_LOG_DIR), log_file='post_tool_use.log')
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# 上传功能
+# ============================================================================
+
+
+def upload_to_api(change_data: dict) -> bool:
+    """
+    同步上传数据到 DevLake API
+
+    Args:
+        change_data: 变更数据字典
+
+    Returns:
+        是否上传成功
+    """
+    try:
+        client = DevLakeClient()
+        client.create_file_changes([change_data])
+        logger.info(f'成功上传文件变更: {change_data.get("file_path")}')
+        return True
+    except Exception as e:
+        logger.error(f'上传文件变更失败: {e}')
+        return False
+
+
+# ============================================================================
+# 临时文件管理（PreToolUse 使用）
+# ============================================================================
+
+def load_before_content(session_id: str, file_path: str) -> str:
+    """
+    从临时文件加载 before_content
+
+    Args:
+        session_id: 会话ID
+        file_path: 文件路径
+
+    Returns:
+        文件的 before_content，如果不存在返回空字符串
+    """
+    temp_file = get_temp_file_path(session_id, file_path)
+
+    try:
+        if os.path.exists(temp_file):
+            with open(temp_file, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+                return data.get('content', '')
+    except Exception:
+        pass
+
+    return ''
+
+
+def get_current_file_content(file_path: str) -> str:
+    """
+    读取文件当前内容
+
+    Args:
+        file_path: 文件路径
+
+    Returns:
+        文件内容，读取失败返回空字符串
+    """
+    try:
+        if os.path.exists(file_path):
+            with open(file_path, 'r', encoding='utf-8') as f:
+                return f.read()
+    except Exception:
+        pass
+
+    return ''
+
+
+# ============================================================================
+# 辅助函数
+# ============================================================================
+
+def get_file_type(file_path: str) -> str:
+    """获取文件类型"""
+    return Path(file_path).suffix.lstrip('.') or 'unknown'
+
+
+def extract_user_info(session_id: str) -> dict:
+    """从环境变量提取用户信息"""
+    return {
+        'user_name': os.getenv('USER', 'unknown'),
+        'project_name': Path(os.getcwd()).name
+    }
+
+
+def should_collect_file(file_path: str) -> bool:
+    """判断是否应该采集该文件"""
+    # 排除敏感文件
+    sensitive_patterns = ['.env', '.secret', '.key']
+    file_path_lower = file_path.lower()
+
+    for pattern in sensitive_patterns:
+        if pattern in file_path_lower:
+            return False
+
+    # 排除二进制文件（通过后缀判断）
+    binary_extensions = {
+        '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico',
+        '.pdf', '.zip', '.tar', '.gz', '.rar',
+        '.exe', '.dll', '.so', '.dylib',
+        '.class', '.pyc', '.pyo'
+    }
+
+    file_ext = Path(file_path).suffix.lower()
+    if file_ext in binary_extensions:
+        return False
+
+    return True
+
+
+# ============================================================================
+# 主逻辑
+# ============================================================================
+
+@run_async
+def main():
+    temp_file = None  # 初始化临时文件路径
+    try:
+        # 读取 Hook 输入
+        input_data = json.load(sys.stdin)
+
+        hook_event_name = input_data.get('hook_event_name')
+        tool_name = input_data.get('tool_name')
+        tool_input = input_data.get('tool_input', {})
+        session_id = input_data.get('session_id')
+
+        # 获取当前工作目录（需要在检查会话前获取）
+        cwd = input_data.get('cwd', os.getcwd())
+
+        # 检查会话是否切换（如果切换会自动结束旧会话）
+        if session_id:
+            try:
+                switched = check_and_switch_session(session_id, cwd, ide_type='claude_code')
+                if switched:
+                    logger.info(f'检测到会话切换，旧会话已自动结束，新会话: {session_id}')
+            except Exception as e:
+                logger.error(f'会话切换检查失败: {e}')
+
+        # 只处理 PostToolUse 事件
+        if hook_event_name != 'PostToolUse':
+            sys.exit(0)
+
+        # 只处理文件修改相关的工具
+        if tool_name not in ['Write', 'Edit', 'NotebookEdit']:
+            sys.exit(0)
+
+        logger.debug(f'PostToolUse Hook 触发 - tool: {tool_name}, session: {session_id}')
+
+        # 提取文件路径
+        file_path = tool_input.get('file_path') or tool_input.get('notebook_path')
+        if not file_path:
+            logger.debug('没有 file_path，跳过')
+            sys.exit(0)
+
+        # 转换为绝对路径
+        if not os.path.isabs(file_path):
+            cwd = input_data.get('cwd', os.getcwd())
+            file_path = os.path.join(cwd, file_path)
+
+        # 检查是否应该采集
+        if not should_collect_file(file_path):
+            logger.debug(f'文件不需要采集（敏感文件或二进制文件）: {file_path}')
+            sys.exit(0)
+
+        logger.info(f'开始处理文件变更: {file_path}')
+
+        # 获取用户信息
+        user_info = extract_user_info(session_id)
+
+        # ====================================================================
+        # v1.3 核心改进：同步上传 + 分支支持
+        # ====================================================================
+
+        # 1. 获取临时文件路径（用于后续清理）
+        temp_file = get_temp_file_path(session_id, file_path)
+
+        # 2. 从 PreToolUse 临时文件加载 before_content
+        before_content = load_before_content(session_id, file_path)
+
+        # 3. 读取当前文件内容（after_content）
+        after_content = get_current_file_content(file_path)
+
+        # 4. 压缩内容（减少传输大小）
+        before_content_gz = compress_content(before_content)
+        after_content_gz = compress_content(after_content)
+
+        # ====================================================================
+        # Git 信息获取策略：基于文件路径获取 Git 上下文（支持 workspace）
+        # - 从文件路径向上查找 .git 目录
+        # - 静态信息（author, email, repo_path）：优先从环境变量读取
+        # - 动态信息（branch, commit）：每次执行 git 命令获取最新值
+        # ====================================================================
+
+        # 5. 获取完整的 Git 上下文（基于文件路径，支持 workspace 多项目）
+        git_context = get_git_context_from_file(file_path, use_env_cache=True)
+        git_author = git_context.get('git_author', 'unknown')
+        git_email = git_context.get('git_email', 'unknown')
+        git_repo_path = git_context.get('git_repo_path', 'unknown')
+        git_branch = git_context.get('git_branch', 'unknown')
+        git_commit = git_context.get('git_commit', 'unknown')
+
+        # 6. 其他配置
+        ide_type = 'claude_code'  # 固定值
+        model_name = os.getenv('CLAUDE_MODEL', 'claude-sonnet-4-5')
+
+        logger.debug(f'Git 信息 - branch: {git_branch}, '
+                    f'commit: {git_commit[:8] if git_commit != "unknown" else "unknown"}, '
+                    f'email: {git_email}, repo: {git_repo_path}')
+
+        # 6. 转换 file_path 为相对路径（使用 git_context 中的 git_root）
+        git_root = git_context.get('git_root')
+        if git_root:
+            try:
+                # 计算相对路径
+                relative_path = os.path.relpath(file_path, git_root)
+                logger.debug(f'文件路径转换: {file_path} -> {relative_path}')
+                file_path = relative_path
+            except Exception as e:
+                # 如果转换失败，保持原路径
+                logger.warning(f'路径转换失败: {e}')
+
+        # 7. 获取 prompt_uuid（关联到具体的 prompt）
+        prompt_uuid = get_current_generation_id(session_id, ide_type='claude_code')
+        logger.debug(f'获取到 prompt_uuid: {prompt_uuid}')
+
+        # 8. 构造上报数据（不包含 diff 计算结果）
+        change_data = {
+            'session_id': session_id,
+            'prompt_uuid': prompt_uuid,                   # 新增：关联到具体的 prompt
+            'user_name': user_info['user_name'],
+            'ide_type': ide_type,                         # IDE 类型
+            'model_name': model_name,                     # AI 模型名称
+            'git_repo_path': git_repo_path,               # Git仓库路径 (namespace/name)
+            'project_name': user_info['project_name'],
+            'file_path': file_path,                       # 相对路径
+            'file_type': get_file_type(file_path),
+            'change_type': 'create' if tool_name == 'Write' else 'edit',
+            'tool_name': tool_name,
+            'before_content_gz': before_content_gz,       # 压缩内容
+            'after_content_gz': after_content_gz,         # 压缩内容
+            'git_branch': git_branch,                     # Git 分支（动态）
+            'git_commit': git_commit,                     # Git commit（动态）
+            'git_author': git_author,                     # Git 作者（环境变量）
+            'git_email': git_email,                       # Git 邮箱（环境变量）
+            'change_time': datetime.now().isoformat(),
+            'cwd': cwd
+        }
+
+        # 9. 同步上传到 API（超时 3 秒）
+        success = upload_to_api(change_data)
+
+        if not success:
+            # 上传失败，保存到本地队列（支持自动重试）
+            logger.warning(f'API 上传失败，保存到本地队列: {file_path}')
+            save_failed_upload(
+                queue_type='file_change',
+                data=change_data,
+                error='API upload failed'
+            )
+
+    except Exception as e:
+        # 任何异常都静默失败，不阻塞 Claude
+        logger.error(f'PostToolUse Hook 执行失败: {e}', exc_info=True)
+    finally:
+        # 10. 清理临时文件（使用 finally 确保一定执行）
+        if temp_file and os.path.exists(temp_file):
+            try:
+                os.remove(temp_file)
+                logger.debug(f'清理临时文件: {temp_file}')
+            except Exception as e:
+                logger.warning(f'清理临时文件失败: {e}')
+
+        # 静默退出
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

devlake_mcp/hooks/pre_tool_use.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+PreToolUse Hook - 在工具执行前记录文件内容
+
+功能：
+1. 拦截 Write/Edit/NotebookEdit 工具
+2. 读取文件的完整内容（before_content）
+3. 保存到临时文件，供 PostToolUse 使用
+
+注意：此 hook 不使用异步执行，因为必须在工具执行前完成文件内容的保存
+"""
+
+import json
+import logging
+import sys
+import os
+from pathlib import Path
+from datetime import datetime
+
+# 导入公共工具（使用包导入）
+from devlake_mcp.utils import get_temp_file_path
+from devlake_mcp.logging_config import configure_logging, get_log_dir
+from devlake_mcp.constants import HOOK_LOG_DIR
+
+# 配置日志（启动时调用一次）
+configure_logging(log_dir=get_log_dir(HOOK_LOG_DIR), log_file='pre_tool_use.log')
+logger = logging.getLogger(__name__)
+
+
+def save_before_content(session_id: str, file_path: str, content: str):
+    """
+    保存文件的 before_content 到临时文件
+
+    Args:
+        session_id: 会话ID
+        file_path: 文件路径
+        content: 文件内容
+    """
+    temp_file = get_temp_file_path(session_id, file_path)
+
+    try:
+        with open(temp_file, 'w', encoding='utf-8') as f:
+            # 保存为 JSON 格式，包含元数据
+            data = {
+                'file_path': file_path,
+                'content': content,
+                'timestamp': datetime.now().isoformat()
+            }
+            json.dump(data, f)
+    except Exception:
+        # 静默失败
+        pass
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+
+        tool_name = input_data.get('tool_name')
+        tool_input = input_data.get('tool_input', {})
+        session_id = input_data.get('session_id')
+
+        # 只处理文件修改工具
+        if tool_name not in ['Write', 'Edit', 'NotebookEdit']:
+            sys.exit(0)
+
+        # 获取文件路径
+        file_path = tool_input.get('file_path')
+        if not file_path:
+            logger.debug(f'工具 {tool_name} 没有 file_path，跳过')
+            sys.exit(0)
+
+        # 转换为绝对路径
+        if not os.path.isabs(file_path):
+            cwd = input_data.get('cwd', os.getcwd())
+            file_path = os.path.join(cwd, file_path)
+
+        logger.debug(f'PreToolUse Hook 触发 - tool: {tool_name}, file: {file_path}')
+
+        # 读取文件当前内容（before_content）
+        before_content = ''
+
+        if os.path.exists(file_path):
+            try:
+                with open(file_path, 'r', encoding='utf-8') as f:
+                    before_content = f.read()
+                logger.debug(f'成功读取文件内容 - 长度: {len(before_content)} 字符')
+            except Exception as e:
+                # 读取失败（如二进制文件），跳过
+                logger.warning(f'读取文件失败（可能是二进制文件）: {e}')
+                sys.exit(0)
+        else:
+            logger.debug('文件不存在（新建文件）')
+
+        # 保存到临时文件
+        save_before_content(session_id, file_path, before_content)
+        logger.info(f'成功保存 before_content: {file_path}')
+
+        # 成功，静默退出
+        sys.exit(0)
+
+    except Exception as e:
+        # 任何异常都静默失败，不影响 AI 执行
+        logger.error(f'PreToolUse Hook 执行失败: {e}', exc_info=True)
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()