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

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

快速开始

npm安装（推荐）

# 首次安装
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命令

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

bundled.js安装（无npm环境）

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 确认后的最终值

使用方法

查看统计

# 当前项目统计
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: 手动记录

# 完美任务(默认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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

从旧版本升级

# 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:

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