Metadata-Version: 2.4
Name: devlake-mcp
Version: 0.5.8
Summary: AI programming data collection tool - supports IDE Hooks for Claude Code, Cursor, and Codex CLI
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: devlake,ai,llm,claude-code,cursor,codex,hooks,ai-programming,code-assistant
Classifier: Development Status :: 4 - Beta
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: 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

[![PyPI version](https://img.shields.io/pypi/v/devlake-mcp.svg)](https://pypi.org/project/devlake-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/devlake-mcp.svg)](https://pypi.org/project/devlake-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

DevLake MCP 是一个 **AI 编程数据采集工具**，通过 IDE Hooks 自动采集 AI 编程数据，用于统计 **AI 出码率**和研发效率指标。

支持三种 IDE：**Claude Code**、**Cursor**、**Codex CLI**

## ✨ 核心特性

- **🎯 自动采集** - 无需手动操作，IDE Hooks 自动记录 AI 编程数据
- **📊 AI 出码率统计** - 精确计算 AI 生成代码在最终提交中的占比
- **🔄 智能重试** - 失败请求自动重试，指数退避策略，数据不丢失
- **🚀 异步执行** - 后台运行，不阻塞 IDE 操作
- **🌐 多 IDE 支持** - Claude Code、Cursor、Codex CLI 全覆盖
- **🛡️ Context Guardian** - Claude Code 上下文 token 分级告警 + Opus 切换提示 + 长空闲提醒 + 状态栏展示（[详见文档](docs/context-guardian.md)）

## Python 版本要求

Python 3.9+ 即可使用全部功能。

## 📦 安装

```bash
# 使用 pipx 安装（推荐）
pipx install devlake-mcp

# 或使用 pip
pip install devlake-mcp
```

```bash
# 验证安装
devlake-mcp --version
```

## ⚙️ 环境配置

<details>
<summary>点击展开详细配置选项</summary>

```bash
# ============================================================
# API 配置（可选）
# ============================================================
export DEVLAKE_BASE_URL="http://devlake.test.chinawayltd.com"
export DEVLAKE_TIMEOUT=15
export DEVLAKE_HTTP_RETRY_COUNT=1

# ============================================================
# Git 配置（必需）
# ============================================================
git config user.name "Your Name"
git config user.email "your.email@example.com"

# ============================================================
# 日志配置（可选）
# ============================================================
export DEVLAKE_MCP_LOGGING_ENABLED=true
export DEVLAKE_MCP_LOG_LEVEL=INFO
export DEVLAKE_MCP_CONSOLE_LOG=false  # 仅开发调试时启用

# ============================================================
# 重试配置（可选）
# ============================================================
export DEVLAKE_RETRY_ENABLED=true
export DEVLAKE_RETRY_MAX_ATTEMPTS=5
export DEVLAKE_RETRY_CLEANUP_DAYS=7
export DEVLAKE_RETRY_CHECK_ON_HOOK=true
```

</details>

---

## 🔌 Claude Code Hooks

### 一键初始化

```bash
# 自动配置 ~/.claude/settings.json（智能合并，保留现有配置）
devlake-mcp init

# 项目级配置（仅当前项目）
devlake-mcp init --project

# 强制覆盖（不推荐）
devlake-mcp init --force
```

### 支持的 Hooks

| Hook | 触发时机 | 功能 |
|------|---------|------|
| **SessionStart** | 会话启动 | 创建 session 记录 |
| **UserPromptSubmit** | 用户提交 prompt | 记录用户输入 |
| **PreToolUse** | 工具使用前 | 缓存文件变更前状态 |
| **PostToolUse** | 工具使用后 | 上传文件变更（diff） |
| **Stop** | AI 循环停止 | 更新会话统计 |
| **StopFailure** | AI 因 API 错误结束 | 记录错误类型和错误详情 |
| **SessionEnd** | 会话结束 | 上传完整 transcript |

### 技术特点

- ✅ 使用 Claude Code 原生 `session_id`，无需额外管理
- ✅ 自动检测会话超时（30 分钟）
- ✅ 异步上传，不阻塞 IDE 操作

---

## 🖱️ Cursor Hooks

### 一键初始化

```bash
# 自动配置 ~/.cursor/hooks.json
devlake-mcp init-cursor

# 项目级配置
devlake-mcp init-cursor --project

# 强制覆盖
devlake-mcp init-cursor --force
```

### 支持的 Hooks（20 个）

| 类别 | Hook | 功能 |
|------|------|------|
| **会话** | `sessionStart` / `sessionEnd` | 创建/结束会话，sessionEnd 自动上传 transcript |
| **Prompt** | `beforeSubmitPrompt` / `afterAgentResponse` / `afterAgentThought` | 记录输入、响应和 AI 思考过程 |
| **工具追踪** | `preToolUse` / `postToolUse` / `postToolUseFailure` | 通用工具调用前后的文件变更追踪 |
| **文件操作** | `beforeReadFile` / `afterFileEdit` | Agent 文件读写追踪 |
| **Tab 补全** | `beforeTabFileRead` / `afterTabFileEdit` | Tab 内联补全写入的代码采集 |
| **Shell** | `beforeShellExecution` / `afterShellExecution` | Shell 命令产生的文件变更 |
| **MCP 工具** | `beforeMCPExecution` / `afterMCPExecution` | MCP 工具调用日志 |
| **子 Agent** | `subagentStart` / `subagentStop` | 子 Agent 生命周期日志 |
| **其他** | `preCompact` / `stop` | 上下文压缩监控、会话循环结束 |

### 技术特点

- ✅ 使用 Cursor 原生 `conversation_id` 作为 session_id
- ✅ `generation_id` 关联同一次 AI 生成的多个文件变更
- ✅ 区分 Agent 编辑（`FileEdit`）和 Tab 补全（`TabEdit`）两种来源
- ✅ 精确工作目录定位（`workspace_roots`）
- ✅ sessionEnd 自动上传 transcript JSONL

---

## ⚡ Codex CLI Hooks

### 一键初始化

```bash
# 自动配置 ~/.codex/hooks.json 并开启 Codex hooks feature
devlake-mcp init-codex
```

### 支持的 Hooks

| Hook | 触发时机 | 功能 |
|------|---------|------|
| **session_start** | 会话启动 | 创建 session 记录（`ide_type=codex`） |
| **user_prompt_submit** | 用户提交 prompt | 记录用户输入 |
| **stop** | AI 完成回复 | PATCH 补全 prompt 记录，同步 transcript |

---

## 🔄 Transcript 同步

所有 IDE 的 transcript 文件会在会话结束时自动上传。也可以手动扫描并补传缺失的 transcript：

```bash
# 扫描并上传（Claude Code + Cursor + Codex 全部）
devlake-mcp sync

# 预览模式，只扫描不上传
devlake-mcp sync --dry-run

# 强制重传（忽略缓存）
devlake-mcp sync --force
```

扫描路径：
- **Claude Code**：`~/.claude/projects*/**/*.jsonl`
- **Cursor**：`~/.cursor/projects/*/agent-transcripts/*.jsonl`
- **Codex**：`~/.codex/sessions/**/*.jsonl`

---

## 🔄 失败重试机制

API 调用失败时，自动保存到本地队列并按指数退避策略重试：

| 重试次数 | 等待时间 |
|---------|---------|
| 第 1 次 | 1 分钟 |
| 第 2 次 | 5 分钟 |
| 第 3 次 | 15 分钟 |
| 第 4 次 | 60 分钟 |
| 第 5 次 | 4 小时 |

```bash
devlake-mcp queue-status   # 查看失败队列
devlake-mcp retry          # 手动触发重试
devlake-mcp queue-clean    # 清理过期记录
```

---

## CLI 命令总览

```bash
# Hooks 初始化
devlake-mcp init                  # Claude Code 全局配置
devlake-mcp init --project        # Claude Code 项目配置
devlake-mcp init-cursor           # Cursor 全局配置
devlake-mcp init-cursor --project # Cursor 项目配置
devlake-mcp init-codex            # Codex 全局配置

# Transcript 同步
devlake-mcp sync                  # 扫描并上传缺失 transcript
devlake-mcp sync --dry-run        # 预览模式
devlake-mcp sync --force          # 强制重传

# 失败队列管理
devlake-mcp queue-status          # 查看失败队列
devlake-mcp retry                 # 手动触发重试
devlake-mcp queue-clean           # 清理过期记录

# 版本信息
devlake-mcp --version
devlake-mcp info
devlake-mcp --help
```

---

## ⚠️ 前置要求

### Git 配置（必需）

```bash
git config user.name "Your Name"
git config user.email "your.email@example.com"
git remote add origin <repository-url>
```

---

## 🐛 故障排查

<details>
<summary>点击查看常见问题解决方案</summary>

### Hook 未执行

1. 检查配置：`.claude/settings.json` 或 `~/.cursor/hooks.json`
2. 查看日志：`tail -f ~/.devlake/logs/claude_hooks.log`（或 `cursor_hooks.log`）
3. 验证 Python：macOS/Linux 用 `which python3`，Windows 用 `where python` 或 `py -0p`
4. 检查 hook command 是否可执行，必要时重新初始化：`devlake-mcp init --force`

### API 调用失败

1. 检查网络：`curl $DEVLAKE_BASE_URL`
2. 查看重试队列：`devlake-mcp queue-status`
3. 手动重试：`devlake-mcp retry`

### 数据未上传

1. 检查 Git 配置：`git config user.name`
2. 启用调试日志：`export DEVLAKE_MCP_LOG_LEVEL=DEBUG`
3. 查看日志：`cat ~/.devlake/logs/claude_hooks.log`

</details>

---

## 📚 相关文档

- **[架构设计](docs/development/DESIGN.md)**
- **[Cursor 集成](docs/integrations/CURSOR_HOOKS.md)**
- **[更新日志](CHANGELOG.md)**

---

## 📄 许可证

[MIT License](LICENSE)
