npm package: @gami-ai/ai-tracking
Description: AI量化追踪系统 - 白泽 | AI Performance Tracking System
Author: zhangzhenyu
Latest version: 4.4.0

# 白泽 - AI量化追踪系统 v4.2.1

> **白泽**（Baize）：上古神兽，通晓万物，能言语，知鬼神之事。取名寓意追踪系统洞察AI协作的本质，量化不可见的能力成长。

## 快速开始

### npm安装（推荐）

```bash
# 首次安装
npm install -g @gami-ai/ai-tracking

# 升级到最新版本（不要用update，有已知Bug）
npm install -g @gami-ai/ai-tracking@latest

# 查看版本
ai-tracking --version
```

**安装后自动配置**：
- ✅ 配置全局Hooks（StatusLine + SessionStart + UserPromptSubmit + PreToolUse + PostToolUse）
- ✅ 复制AI-TRACKING.md到~/.claude/
- ✅ 更新CLAUDE.md添加@AI-TRACKING.md引用
- ✅ 重启Claude Code后，所有项目自动启用追踪

### CLI命令

```bash
ai-tracking init              # 初始化当前项目
ai-tracking stats             # 查看当前项目统计
ai-tracking stats --global    # 查看全局统计
ai-tracking stats --all       # 查看所有项目对比
ai-tracking record "任务"     # 手动记录任务
ai-tracking --help            # 查看帮助
```

### bundled.js安装（无npm环境）

```bash
node ~/.claude/shared/ai-tracking/releases/v4.2.1/install-v4.2.1-bundled.js
```

## v4.2 核心特性

### v4.2.0 更新
- ✅ **混合事件追踪**: Hook实时捕获 + AI最终确认，防止compact/continue数据丢失
- ✅ **上下文感知修正检测**: 结合对话历史判断是否为真正的修正事件
- ✅ **Tracker抽象层**: 为未来Agent-Agnostic架构预留扩展能力
- ✅ **Pending事件机制**: Hook宽松捕获，AI精确确认，减少误判
- ✅ **PostToolUse Hook**: 自动捕获工具拒绝事件

### v4.1.x 更新
- ✅ **npm包发布**: `npm install -g @gami-ai/ai-tracking`
- ✅ **自动升级**: `npm install -g @gami-ai/ai-tracking@latest`
- ✅ **CLI命令**: `ai-tracking init/stats/record`
- ✅ **新版本检测**: 启动时自动检测并提醒升级

### v4.0.x 更新
- ✅ **SSS级别**: 新增最高难度等级，只能通过升级获得(权重4.0)
- ✅ **扣分系数**: 高难度+高复杂度任务扣分减少，保护高质量任务
- ✅ **单一得分指标**: 移除"理解度+评分"双指标，统一为"得分"(0-100)
- ✅ **加权平均**: 按任务难度加权计算，简单任务不会大幅拉低分数
- ✅ **动态调节**: 低于平均分时向平均分靠拢（保底机制）
- ✅ **权重系统**: SSS=4.0, S=3.0, A=2.0, B=1.5, C=1.0

### 保留特性

- ✅ **任务难度等级**: SSS/S/A/B/C五级难度自动检测
- ✅ **任务类型分类**: feature/bugfix/refactor/design/config/debug
- ✅ **能力成长追踪**: 基于近30天历史对比
- ✅ **文件复杂度提升**: 文件操作>25时自动提升难度
- ✅ **复杂度计算**: 交互+文件双维度
- ✅ **全局Hooks架构**: 零配置体验
- ✅ **自动初始化新项目**: SessionStart hook自动检测

## 架构说明

### npm全局安装架构

```
npm全局目录
└── node_modules/@gami-ai/ai-tracking/
    ├── bin/
    │   ├── cli.js              ← CLI入口
    │   └── postinstall.js      ← 安装后自动配置
    ├── tracker.js              ← 核心抽象层 (v4.2新增)
    ├── session-start.js        ← 自动初始化 + 新版本检测
    ├── increment.js            ← 交互计数 + 修正检测
    ├── pre-tool-use.js         ← 文件操作追踪
    ├── post-tool-use.js        ← 拒绝事件捕获 (v4.2新增)
    ├── statusline.js           ← StatusLine显示
    ├── calculator.js           ← 得分计算引擎
    ├── record-task.js          ← 任务记录
    ├── stats.js                ← 统计查看
    ├── init.js                 ← 项目初始化
    ├── dashboard.js            ← 可视化仪表盘
    └── AI-TRACKING.md          ← AI指令文档

~/.claude/
├── settings.json               ← 全局Hooks配置（postinstall自动配置）
├── CLAUDE.md                   ← 添加@AI-TRACKING.md引用
└── AI-TRACKING.md              ← AI指令文档（postinstall复制）

项目层（数据完全独立）
├── 项目A/.claude/
│   ├── ai-tracking-counter.json  ← 追踪数据
│   └── ai-tracking-events.json   ← 事件缓冲区 (v4.2新增)
├── 项目B/.claude/...
└── 项目C/.claude/...
```

**核心机制**：通过 `process.cwd()` 动态定位项目数据，实现多项目数据隔离

### v4.2 混合事件追踪架构

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Hook 捕获层   │ ──→ │  AI 确认层      │ ──→ │   记录层        │
│  (实时、宽松)   │     │  (审核、精确)   │     │  (最终计分)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
   post-tool-use.js          AI 判断              record-task.js
   increment.js
         ↓                                              ↓
   ┌─────────────────────────────────────────────────────┐
   │              tracker.js (核心抽象层)                │
   │  - recordEvent(type, context)  记录pending事件     │
   │  - getPendingEvents()          获取待确认事件       │
   │  - confirmEvents(counts)       AI确认后更新        │
   │  - resetEvents()               任务记录后重置       │
   └─────────────────────────────────────────────────────┘
```

**工作流程**：
1. **Hook 捕获**: PostToolUse/UserPromptSubmit 实时捕获事件到 pending 数组
2. **AI 确认**: 任务记录时 AI 审核 pending 事件，剔除误判
3. **最终计分**: CLI 参数作为 AI 确认后的最终值

## 使用方法

### 查看统计

```bash
# 当前项目统计
ai-tracking stats

# 全局汇总统计
ai-tracking stats --global

# 所有项目明细排行
ai-tracking stats --all
```

### 自然语言触发

在对话中直接说：
- **"当前统计"** / **"项目统计"** → 显示当前项目统计
- **"全局统计"** / **"我的统计"** → 全局汇总统计
- **"项目对比"** / **"所有项目"** → 项目排行榜
- **"显示dashboard"** / **"打开仪表盘"** → 可视化仪表盘
- **"任务完成"** / **"记录任务"** → 自动评分记录

### 任务记录

**方式1: 自动记录（推荐）**

任务完成时对AI说：
```
任务完成
```

AI会自动：
1. 回顾本次会话完成的任务描述
2. **搜索会话历史中的文本标记**：
   - `[Request interrupted by user]` → 统计打断次数
   - `The user doesn't want to proceed` → 统计拒绝次数
3. 判断任务难度等级（S/A/B/C）
4. 调用record-task.js并传入正确参数
5. 自动计算得分

**方式2: 手动记录**

```bash
# 完美任务(默认0事件)
ai-tracking record "实现用户登录功能"

# 有1次打断的任务
ai-tracking record "修复支付Bug" 1 0 0

# 指定A级难度
ai-tracking record "实现功能" 0 0 0 A
```

## 核心指标

### 得分 (Score): 0-100

**含义**: 综合反映任务完成质量

**计算公式**: `原始得分 + 动态调节`

**原始得分** = 30(基础) + 难度加分 + 复杂度加分 + 奖励 - 扣分

**难度加分**:
| 难度 | 加分 | 权重 | 扣分系数 |
|-----|------|-----|---------|
| C级(简单) | +0 | 1.0 | 1.0 |
| B级(中等) | +15 | 1.5 | 0.85 |
| A级(困难) | +25 | 2.0 | 0.7 |
| S级(突破) | +40 | 3.0 | 0.5 |
| SSS级(传奇) | +50 | 4.0 | 0.3 |

**注**: SSS级只能通过升级获得（S级 + 超复杂/文件>40/交互>35）

**复杂度加分**:
| 复杂度 | 加分 | 扣分系数 |
|-------|------|---------|
| 简单 | +0 | 1.0 |
| 中等 | +5 | 0.85 |
| 复杂 | +15 | 0.7 |
| 超复杂 | +25 | 0.55 |

**奖励加分**:
- 零事件完成: +5分
- 低事件密度(<10%): +3分
- 成长奖励: 显著+5, 稳步+3, 稳定+2

**扣分** (乘以扣分系数):
- 打断: -15分/次 × 扣分系数
- 拒绝: -25分/次 × 扣分系数
- 修正: -10分/次 × 扣分系数

**扣分系数计算**: `min(难度扣分系数, 复杂度扣分系数)`

### 动态调节（保底机制）

当原始得分 < 当前平均分时，向平均分靠拢：
```
最终得分 = 原始得分 + (平均分 - 原始得分) × 调节强度
```

**调节强度**:
| 难度 | 调节强度 | 说明 |
|-----|---------|------|
| C级 | 0.5 | 向平均分靠拢50% |
| B级 | 0.3 | 向平均分靠拢30% |
| A级 | 0.1 | 轻微调节 |
| S级 | 0 | 不调节，靠实力 |
| SSS级 | 0 | 不调节，靠实力 |

**注意**: 高于平均分的任务不调节，S/SSS级任务完全靠实力

### 加权平均

```
加权平均 = Σ(得分 × 权重) / Σ(权重)
```

**效果**: 简单任务权重低，不会大幅拉低辛苦刷上去的分数

### 难度等级检测

**【优先】AI语义判断** - 根据任务实际工作内容判断：

| 难度 | 语义判断标准 |
|------|-------------|
| **SSS级(传奇)** | **只能通过升级获得** |
| **S级(突破)** | 系统架构级重大改动、引入新技术栈/框架、大规模重构 |
| **A级(困难)** | 跨模块协作开发、复杂业务逻辑、深度性能优化 |
| **B级(中等)** | 单模块功能开发、标准CRUD实现、常规业务功能 |
| **C级(简单)** | 配置文件修改、简单Bug修复、文档更新、UI微调 |

**文件复杂度提升**: `filesRead + filesModified × 2 > 25` 时自动提升一级

### 复杂度计算

**交互维度**:
| 交互次数 | 复杂度 |
|---------|--------|
| ≤5 | 简单 |
| 6-15 | 中等 |
| 16-30 | 复杂 |
| >30 | 超复杂 |

**文件维度** (读+改×2):
| 文件数 | 复杂度 |
|-------|--------|
| ≤5 | 简单 |
| 6-15 | 中等 |
| 16-30 | 复杂 |
| >30 | 超复杂 |

**综合判断**: 取两个维度中更高的复杂度

### StatusLine显示
```
交互:63 | 任务:9 | 加权均分:72
```

## 升级说明

### 新版本检测

v4.1.1起，每次启动会自动检测npm上是否有新版本：

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⬆️  发现新版本 v4.2.0 (当前 v4.1.1)
   运行: npm install -g @gami-ai/ai-tracking@latest
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 从旧版本升级

```bash
# npm方式升级（不要用update，有已知Bug）
npm install -g @gami-ai/ai-tracking@latest

# 重启Claude Code使配置生效
```

升级会自动：
1. ✅ 保留所有历史数据
2. ✅ 自动迁移旧字段
3. ✅ 更新全局Hooks配置
4. ✅ 更新AI-TRACKING.md指令

## 常见问题

### Q: npm安装后hooks不生效？
A:
1. 检查 `~/.claude/settings.json` 是否有hooks配置
2. 确认路径指向npm全局目录
3. 重启Claude Code

### Q: StatusLine不显示怎么办？
A:
1. 检查 `~/.claude/settings.json` 中是否配置了statusLine
2. 重启Claude Code
3. 运行 `npm install -g @gami-ai/ai-tracking --force` 重新安装

### Q: 如何卸载？
A:
```bash
npm uninstall -g @gami-ai/ai-tracking
```
然后手动删除 `~/.claude/settings.json` 中的hooks配置

### Q: 加权平均和普通平均有什么区别？
A: 普通平均对所有任务一视同仁，简单任务会拉低分数。加权平均根据难度加权，S级任务权重是C级的3倍，辛苦完成的高难度任务不会被简单任务冲淡。

## 版本历史

### v4.2.0 (2025-12-26)
- ✅ **混合事件追踪**: Hook实时捕获 + AI最终确认
- ✅ **Tracker抽象层**: 为Agent-Agnostic架构预留
- ✅ **PostToolUse Hook**: 自动捕获拒绝事件
- ✅ **上下文感知修正检测**: 减少误判

### v4.1.x (2025-12-25)
- ✅ **npm包发布**: 支持npm全局安装
- ✅ **CLI命令**: ai-tracking init/stats/record
- ✅ **新版本检测**: 启动时自动检测并提醒升级

### v4.0.x (2025-12-24) - 白泽
- ✅ **SSS级别**: 新增最高难度等级(权重4.0)
- ✅ **单一得分指标**: 统一为得分(0-100)
- ✅ **加权平均**: 按任务难度加权计算
- ✅ **动态调节**: 保底机制

### v3.5 (2025-12-23)
- ✅ **任务难度等级**: S/A/B/C四级自动检测
- ✅ **任务类型分类**: feature/bugfix/refactor/design/config/debug
- ✅ **能力成长追踪**: 基于近30天历史对比

---

**版本**: v4.2.1 (白泽)
**最后更新**: 2025-12-26
**npm**: https://www.npmjs.com/package/@gami-ai/ai-tracking