# xperf-claude-code-plugin

**Repository Path**: stkid/xperf-claude-code-plugin

## Basic Information

- **Project Name**: xperf-claude-code-plugin
- **Description**: xperf plugin for claude code
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xperf — 通智算融合 Top-down 性能分析插件

> 为 AI Agent 工作负载构建全栈性能可观测性，基于通智算融合 Top-down 理论，扩展 Intel 微架构 Top-down 方法论到三个计算域。

## ✨ 核心特性

- **零侵入自动采集** — 通过 Claude Code hooks（PreToolUse/PostToolUse/Stop）自动记录每次 Tool 调用的时间数据，无需在 Agent 代码中手动插入 SDK 标注
- **三域归属自动推导** — Bash/Read/Write → 通算域(compute)，MCP__xperf → 融合域(fused)，MCP__llm → 智算域(intelligent)
- **L1-L4 层级钻取** — Supply → Processing → Waste → Effective，每类 >20% 自动钻取到瓶颈根因
- **优化建议路径** — Supply>40%→融合域先看；Processing>40%→智算域先看；Waste>30%→通算域先看
- **多格式报告** — JSON / Text / HTML 输出，支持单 Turn 和会话聚合分析

## 🏗️ 架构

```
数据流：
  Claude Code hooks (自动采集) → .xperf/traces/ → MCP server (分析) → 报告

5 个 Hook：
  SessionStart  → 创建 session buffer，开始 Turn 计时
  PreToolUse    → 记录 tool span 开始时间
  PostToolUse   → 记录 tool span 完成 + duration → 推导域归属
  PostToolUseFailure → 记录 Waste 事件
  Stop          → flush 当前 Turn trace 到 JSON 文件
```

## 📦 安装

### 从 marketplace 安装（推荐）

```bash
# 1. 添加 marketplace
/plugin marketplace add stkid/xperf

# 2. 安装插件
/plugin install xperf@xperf-marketplace
```

### 从 Git 仓库安装

```bash
# 直接加载本地插件（用于开发测试）
claude --plugin-dir ./claude-code-plugin

# 或从远程 URL 安装
/plugin install https://gitee.com/stkid/xperf.git
```

## 🔧 使用

安装后插件自动启用，hooks 在每次 Claude Code Tool 调用时自动采集数据。

### 查看采集状态

```
/xperf
```

调用 `xperf__get_status` 查看当前 trace 文件数量和会话列表。

### 单 Turn 分析

调用 `xperf__analyze_turn` 分析最近的 Turn 性能瓶颈。

### 会话聚合分析

调用 `xperf__analyze_session` 分析整个会话的性能趋势。

### CLI 命令行分析

```bash
xperf analyze turn .xperf/traces/<session>/turn_001.json --format html --depth L3
xperf analyze session .xperf/traces/<session>/ --format text
```

## 📊 报告解读

报告包含四类时间分布：

| 类别 | 含义 | 优化方向 |
|------|------|----------|
| **Supply** | 等待资源供应 | 预热、缓存、连接池 |
| **Processing** | 处理慢 | 量化、蒸馏、算法优化 |
| **Waste** | 无效工作 | 减少重试、校验前置、截断控制 |
| **Effective** | 有效工作 | 必须保留，是性能基线 |

三个计算域：

| 域 | 含义 | 来源 |
|----|------|------|
| **通算域** (compute) | CPU 侧工作 | prompt组装、tool调用、response解析 |
| **智算域** (intelligent) | GPU/LLM 侧 | LLM推理、prefill、decode |
| **融合域** (fused) | 跨域瞬间 | TTFT、streaming gap、数据传输 |

## 🧪 测试

```bash
pytest tests/ -v                          # 237 tests, all passing
pytest tests/plugin/test_collector.py -v   # 37 plugin-specific tests
```

## 📐 理论基础

基于 `docs/software-topdown-performance-theory.md` 中的核心理论规格：

- **执行位置原则** — CPU→通算域, GPU→智算域, 跨域瞬间→融合域
- **融合域是薄接口不是厚桥** — 只捕获跨域瞬间
- **可测性分级** — A(直接可测)、B(间接)、C(主观) — 实时使用 A/B 级
- **Waste Bound 可测性** — 只有 A/B 级客观可测指标用于实时 Topdown

## 📄 License

MIT — Wei Li