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

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

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

## 快速开始

### 一键安装（推荐）

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

**安装后立即生效**：
- ✅ 配置全局Hooks（StatusLine + SessionStart + UserPromptSubmit + PreToolUse）
- ✅ 配置CLAUDE.md引用（自动添加 `@AI-TRACKING.md`）
- ✅ 初始化当前项目追踪数据
- ✅ 重启Claude Code后，所有项目自动启用追踪

## v4.0 核心特性

### 对使用者的变化

1. **单一得分指标** - 移除"理解度+评分"双指标，统一为"得分"(0-100)
2. **加权平均** - 按任务难度加权计算，简单任务不会大幅拉低分数
3. **动态调节** - 低于平均分时向平均分靠拢（保底机制）
4. **权重系统** - S=3.0, A=2.0, B=1.5, C=1.0

### 保留特性

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

### 全局Hooks架构

```
全局层（所有项目共享）
├── ~/.claude/settings.json          ← 全局Hooks配置
└── ~/.claude/shared/ai-tracking/    ← JS脚本目录
    ├── session-start.js             ← 自动初始化新项目
    ├── increment.js                 ← 交互计数
    ├── pre-tool-use.js              ← 文件操作追踪
    ├── statusline.js                ← StatusLine显示
    ├── calculator.js                ← 得分计算引擎
    └── ...

项目层（数据完全独立）
├── 项目A/.claude/ai-tracking-counter.json  ← 项目A的数据
├── 项目B/.claude/ai-tracking-counter.json  ← 项目B的数据
└── 项目C/.claude/ai-tracking-counter.json  ← 项目C的数据
```

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

## 核心文件

### 共享脚本目录 (`~/.claude/shared/ai-tracking/`)

**核心运行时**:
1. `session-start.js` - 自动初始化新项目，显示统计快照
2. `increment.js` - 交互自动计数
3. `pre-tool-use.js` - 文件操作追踪
4. `statusline.js` - StatusLine实时显示
5. `calculator.js` - 得分计算引擎（v4.0重写）
6. `record-task.js` - 任务记录与自动评分
7. `init.js` - 支持静默模式和交互模式
8. `stats.js` - 统计查看(支持 --global --all)
9. `dashboard.js` - 全局可视化仪表盘
10. `update-index.js` - 项目索引维护

**安装工具**:
- `generate-installer.js` - 生成bundled安装包

**文档**:
- `README.md` - 本文档
- `ROADMAP.md` - 未来计划
- `~/.claude/AI-TRACKING.md` - AI自动追踪指令

### 全局配置 (`~/.claude/settings.json`)

```json
{
  "statusLine": {
    "type": "command",
    "command": "node \"~/.claude/shared/ai-tracking/statusline.js\""
  },
  "hooks": {
    "SessionStart": [...],      // 自动初始化新项目
    "UserPromptSubmit": [...],  // 交互计数
    "PreToolUse": [...]         // 文件操作追踪
  }
}
```

### 项目数据 (`.claude/`)
- `ai-tracking-counter.json` - 追踪数据（自动创建）
- `.statusline-cache` - StatusLine缓存（自动生成）

## 使用方法

### 安装系统

```bash
# 一键安装v4.0
node ~/.claude/shared/ai-tracking/releases/v4.0/install-v4.0-bundled.js

# 重启Claude Code使hooks生效
# 之后所有项目自动启用追踪
```

### 查看统计

```bash
# 当前项目统计
node ~/.claude/shared/ai-tracking/stats.js

# 全局汇总统计
node ~/.claude/shared/ai-tracking/stats.js --global

# 所有项目明细排行
node ~/.claude/shared/ai-tracking/stats.js --all

# 可视化仪表盘
node ~/.claude/shared/ai-tracking/dashboard.js
```

### 自然语言触发

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

### 任务记录

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

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

AI会自动：
1. 回顾本次会话完成的任务描述
2. **搜索会话历史中的文本标记**：
   - `[Request interrupted by user]` → 统计打断次数
   - `The user doesn't want to proceed` → 统计拒绝次数
3. 从currentSession获取文件操作计数
4. 调用record-task.js并传入正确参数
5. 自动计算得分

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

```bash
# 完美任务(默认0事件)
node ~/.claude/shared/ai-tracking/record-task.js "实现用户登录功能"

# 有1次打断的任务
node ~/.claude/shared/ai-tracking/record-task.js "修复支付Bug" 1 0 0

# 复杂任务(2次打断,1次拒绝,1次修正)
node ~/.claude/shared/ai-tracking/record-task.js "重构订单模块" 2 1 1

# 用户指定A级难度
node ~/.claude/shared/ai-tracking/record-task.js "实现功能" 0 0 0 A
```

## 核心指标

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

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

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

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

**难度加分**:
| 难度 | 加分 | 权重 |
|-----|------|-----|
| C级(简单) | +0 | 1.0 |
| B级(中等) | +15 | 1.5 |
| A级(困难) | +25 | 2.0 |
| S级(突破) | +40 | 3.0 |

**复杂度加分**:
| 复杂度 | 加分 |
|-------|------|
| 简单 | +0 |
| 中等 | +5 |
| 复杂 | +15 |
| 超复杂 | +25 |

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

**扣分** (直接扣，不乘系数):
- 打断: -15分/次
- 拒绝: -25分/次
- 修正: -10分/次

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

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

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

**注意**: 高于平均分的任务不调节

### 加权平均

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

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

### 难度等级检测

| 难度 | 识别关键词 |
|------|-----------|
| **S级** | 架构/重构/迁移/新技术/升级/全面/系统性/底层/核心改造/统一 |
| **A级** | 跨模块/系统设计/架构设计/方案设计/复杂逻辑/性能优化/多系统/集成 |
| **B级** | 功能/实现/开发/新增/添加 |
| **C级** | 修复/配置/调整/小改动 |

**检测优先级**: S → A → B → C
**无关键词时**: 默认为C级
**文件复杂度提升**: `filesRead + filesModified × 2 > 25` 时自动提升一级

### 复杂度计算

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

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

**文件类型权重**:
- 配置文件(.md/.json等): ×0.3
- 代码文件: ×1.0

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

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

## 数据结构

### 项目数据文件 (`.claude/ai-tracking-counter.json`)

```json
{
  "version": "4.0",
  "projectName": "my-project",
  "projectType": "java-backend",
  "projectPath": "/path/to/project",
  "count": 63,
  "lastUpdate": "2025-12-24T12:00:00.000Z",
  "currentSession": {
    "interactions": 12,
    "filesRead": 5,
    "filesModified": 3,
    "startTime": "2025-12-24T10:00:00.000Z",
    "configRead": 2,
    "configModified": 1
  },
  "history": [
    {
      "timestamp": "2025-12-24T11:00:00.000Z",
      "task": "实现用户登录功能",
      "score": 85,
      "rawScore": 85,
      "weight": 1.5,
      "adjusted": false,
      "interactions": 10,
      "filesRead": 5,
      "filesModified": 3,
      "complexity": "中等",
      "difficulty": "B",
      "taskType": "feature",
      "growthBonus": {
        "bonus": 2,
        "level": "稳步成长"
      },
      "events": {
        "interruptions": 0,
        "rejections": 0,
        "corrections": 0,
        "duration": 0
      }
    }
  ]
}
```

### 全局项目索引 (`~/.claude/shared/ai-tracking/.projects-index.json`)

```json
{
  "projects": [
    {
      "name": "my-project",
      "path": "/path/to/project",
      "type": "java-backend",
      "lastActive": "2025-12-24T12:00:00.000Z"
    }
  ]
}
```

## 开发者指南

### 生成安装包

```bash
cd ~/.claude/shared/ai-tracking
node generate-installer.js
```

生成的文件位于：`releases/v4.0/install-v4.0-bundled.js`

### 安装包更新必须项

更新 `generate-installer.js` 时，必须确保安装包包含以下功能：

| 必须项 | 说明 | 代码位置 |
|-------|------|---------|
| **解压脚本文件** | 所有核心JS脚本 + AI-TRACKING.md | SCRIPTS数组 + ENCODED_FILES |
| **配置Hooks** | SessionStart, UserPromptSubmit, PreToolUse | settings.hooks配置 |
| **配置StatusLine** | statusline.js路径 | settings.statusLine配置 |
| **配置CLAUDE.md引用** | 添加`@AI-TRACKING.md`到CLAUDE.md | claudeMdPath逻辑 |
| **清理旧配置** | 移除废弃的hooks（如PostToolUse） | delete settings.hooks.xxx |

**关键检查点**：
1. `@AI-TRACKING.md` 引用必须添加到 `~/.claude/CLAUDE.md`，否则AI无法读取追踪指令
2. 新增的脚本必须加入 SCRIPTS 数组
3. 废弃的hooks必须在安装时清理

### 架构设计：process.cwd() 动态定位

```javascript
// 所有脚本都使用这个机制
const COUNTER_FILE = path.join(process.cwd(), '.claude', 'ai-tracking-counter.json');
//                              ↑ 获取当前工作目录（即当前项目路径）
```

**工作流程**：
1. Claude Code打开项目A → process.cwd() = 项目A路径
2. SessionStart hook触发 → session-start.js执行
3. 检查项目A/.claude/ai-tracking-counter.json是否存在
4. 不存在 → 自动运行init.js初始化
5. 存在 → 显示项目统计快照

**数据隔离效果**：
- 项目A: 读写项目A/.claude/ai-tracking-counter.json
- 项目B: 读写项目B/.claude/ai-tracking-counter.json
- **完全隔离，互不影响**

## 升级说明

### 从 v3.x 升级到 v4.0

执行安装脚本会自动：

1. ✅ 保留所有历史数据
2. ✅ 自动迁移旧字段（understanding → score）
3. ✅ 更新全局Hooks配置
4. ✅ 更新AI-TRACKING.md指令

### 版本对比

| 功能 | v3.4 | v3.5 | v4.0 |
|------|------|------|------|
| 全局Hooks架构 | ✅ | ✅ | ✅ |
| 自动初始化新项目 | ✅ | ✅ | ✅ |
| 零配置体验 | ✅ | ✅ | ✅ |
| 复杂度系数 | ✅ | ✅ | ✅ |
| 文件操作维度 | ✅ | ✅ | ✅ |
| **任务难度等级** | ❌ | ✅ | ✅ |
| **任务类型分类** | ❌ | ✅ | ✅ |
| **能力成长追踪** | ❌ | ✅ | ✅ |
| **单一得分指标** | ❌ | ❌ | ✅ |
| **加权平均** | ❌ | ❌ | ✅ |
| **动态调节** | ❌ | ❌ | ✅ |
| **权重系统** | ❌ | ❌ | ✅ |

## 分享给同事

把这个文件发给同事即可：
```
~/.claude/shared/ai-tracking/releases/v4.0/install-v4.0-bundled.js
```

同事运行后重启Claude Code即可使用。

## 注意事项

1. **Node.js版本**: 要求 Node.js >= 14.0
2. **文件权限**: 确保有写入 `~/.claude/` 目录的权限
3. **数据备份**: 升级前建议备份 `.claude/ai-tracking-counter.json`
4. **重启生效**: 安装或升级后需**重启Claude Code**使hooks生效
5. **自动初始化**: 新项目会自动初始化，无需手动操作
6. **数据隔离**: 每个项目数据完全独立，互不影响
7. **数据迁移**: v3.x的历史数据会自动迁移到v4.0格式

## 常见问题

### Q: v4.0的主要改进是什么？
A:
1. **单一得分指标** - 移除理解度和评分双指标，统一为得分(0-100)
2. **加权平均** - 简单任务不会大幅拉低分数
3. **动态调节** - 低分任务有保底机制
4. **权重系统** - 不同难度任务权重不同

### Q: 老数据会丢失吗？
A: 不会。v3.x的历史数据（understanding字段）会自动迁移到v4.0的score字段。

### Q: StatusLine不显示怎么办？
A:
1. 检查 `~/.claude/settings.json` 中是否配置了statusLine
2. 重启Claude Code
3. 检查 `~/.claude/shared/ai-tracking/statusline.js` 是否存在

### Q: 交互计数不增加怎么办？
A:
1. 检查 `~/.claude/settings.json` 中UserPromptSubmit hook配置
2. 检查 `~/.claude/shared/ai-tracking/increment.js` 是否存在
3. 重启Claude Code

### Q: 如何禁用某个项目的追踪？
A: 删除该项目的 `.claude/ai-tracking-counter.json` 文件即可

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

## 版本历史

### v4.0 (2025-12-24) - 白泽
- ✅ **单一得分指标**: 移除理解度和评分，统一为得分(0-100)
- ✅ **加权平均**: 按任务难度加权计算
- ✅ **动态调节**: 低于平均分时向平均分靠拢（保底机制）
- ✅ **权重系统**: S=3.0, A=2.0, B=1.5, C=1.0
- ✅ **数据迁移**: 自动迁移v3.x历史数据

### v3.5 (2025-12-23)
- ✅ **任务难度等级**: S/A/B/C四级自动检测
- ✅ **任务类型分类**: feature/bugfix/refactor/design/config/debug
- ✅ **能力成长追踪**: 基于近30天历史对比
- ✅ **复杂度计算改进**: 提高阈值，增加文件类型权重
- ✅ **关键词难度检测**: 支持架构/迁移/性能优化等关键词
- ✅ **文件复杂度提升**: 文件操作>25时自动提升难度

### v3.4 (2025-12-11)
- ✅ **文件操作维度**: 复杂度计算新增文件读取数、修改数
- ✅ **综合复杂度评估**: 交互次数 + 文件操作规模双维度
- ✅ **移除工具失败事件**: toolFailures与理解度无关
- ✅ **PreToolUse hook**: 替代PostToolUse，追踪文件操作

### v3.2 (2025-12-10)
- ✅ **复杂度系数**: 根据交互次数动态调整扣分力度
- ✅ **加分机制**: 零事件奖励、低密度奖励、复杂任务奖励
- ✅ **修正事件**: 新增corrections事件类型

### v3.0 (2025-12-10)
- ✅ **全局Hooks架构**: 统一配置，多项目共享
- ✅ **自动初始化新项目**: SessionStart hook自动检测和初始化
- ✅ **零配置体验**: 用户无需手动初始化新项目
- ✅ **数据完全隔离**: 通过process.cwd()动态定位项目数据

### v2.1 (2024-12-10)
- ✅ 混合模式功能（全局统计、项目对比、仪表盘）
- ✅ 项目元数据支持
- ✅ 自动项目索引

### v2.0 (2024-12-10)
- ✅ 新指标体系：理解度 + 评分
- ✅ 自动计算，无需用户输入
- ✅ 事件追踪基础设施

### v1.0 (2024-12-09)
- 首次正确率 + 代码采纳率 + 评分
- 手动输入评分参数

---

**版本**: v4.0 (白泽)
**最后更新**: 2025-12-24
**作者**: AI量化追踪项目组