Navigator Session Statistics Skill

展示实时效率报告，包括基线比较，使Navigator的价值可量化和可分享。

何时调用

当用户：

说“显示我的统计数据”，“显示会话统计数据”，“显示指标”
问“我有多高效？”，“我节省了多少？”
说“显示我的Navigator报告”，“效率报告”
想要看到令牌节省或会话性能
说“显示影响”，“证明Navigator有效”

不要调用如果：

用户刚开始会话（<5条消息）
项目中未初始化Navigator
用户只询问特定指标（直接回答）

执行步骤

第1步：检查Navigator初始化

验证Navigator是否设置：

if [ ! -f ".agent/DEVELOPMENT-README.md" ]; then
  echo "❌ Navigator未在此项目中初始化"
  echo "先运行'Initialize Navigator'"
  exit 1
fi

第2步：运行增强会话统计

执行增强会话统计脚本：

# 检查增强脚本是否存在
if [ ! -f "scripts/session-stats.sh" ]; then
  echo "❌ 会话统计脚本未找到"
  echo "此功能需要Navigator v3.5.0+"
  exit 1
fi

# 运行统计脚本
bash scripts/session-stats.sh

此脚本输出可解析的shell变量：

BASELINE_TOKENS - 所有.agent/文档的总大小
LOADED_TOKENS - 实际在会话中加载（估计）
TOKENS_SAVED - 差异
SAVINGS_PERCENT - 节省百分比
EFFICIENCY_SCORE - 0-100分数
CACHE_EFFICIENCY - 来自OpenTelemetry
CONTEXT_USAGE_PERCENT - 估计的上下文填充
TIME_SAVED_MINUTES - 估计节省的时间

第3步：计算效率分数

使用预定义函数计算分数：

# 从session-stats.sh提取指标
source <(bash scripts/session-stats.sh)

# 使用预定义函数计算效率分数
EFFICIENCY_SCORE=$(python3 skills/nav-stats/functions/efficiency_scorer.py \
  --tokens-saved-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT})

第4步：格式化和显示报告

使用预定义函数格式化视觉报告：

# 生成格式化报告
python3 skills/nav-stats/functions/report_formatter.py \
  --baseline ${BASELINE_TOKENS} \
  --loaded ${LOADED_TOKENS} \
  --saved ${TOKENS_SAVED} \
  --savings-percent ${SAVINGS_PERCENT} \
  --cache-efficiency ${CACHE_EFFICIENCY} \
  --context-usage ${CONTEXT_USAGE_PERCENT} \
  --efficiency-score ${EFFICIENCY_SCORE} \
  --time-saved ${TIME_SAVED_MINUTES}

输出格式：

╔══════════════════════════════════════════════════════╗
║          NAVIGATOR效率报告                 ║
╚══════════════════════════════════════════════════════╝

📊 令牌使用情况
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
加载的文档：        12,000令牌
基线（所有文档）：        150,000令牌
节省的令牌：               138,000令牌（92% ↓）

💾 缓存性能
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
缓存效率：              100.0%（完美）

📈 会话指标
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
上下文使用情况：                      35%（优秀）
效率分数：                94/100（优秀）

⏱️  节省的时间
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
估计节省的时间：          ~42分钟

💡 这意味着什么
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Navigator加载的令牌比加载所有文档少了92%。
您的上下文窗口有65%可用于实际工作。

🎯 建议
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 出色的效率 - 继续使用延迟加载策略
✅ 上下文使用健康 - 有足够的空间用于工作

分享您的效率：截取屏幕截图！#ContextEfficiency

第5步：添加上下文特定建议

根据效率分数，提供可操作的建议：

如果efficiency_score < 70：

⚠️  建议
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  令牌节省低于目标（70%+）
→ 检查：您是否加载了比需要的更多的文档？
→ 技巧：使用navigator查找文档，不要一开始就加载全部

阅读更多：.agent/philosophy/CONTEXT-EFFICIENCY.md

如果context_usage > 80%：

⚠️  建议
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  上下文使用率高（80%+）
→ 考虑：创建上下文标记并紧凑
→ 技巧：在完成子任务后进行紧凑

阅读更多：.agent/philosophy/ANTI-PATTERNS.md

如果cache_efficiency < 80%：

⚠️  建议
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  缓存效率低（<80%）
→ 检查：CLAUDE.md配置正确？
→ 技巧：确保启用了提示缓存

阅读更多：.agent/philosophy/PATTERNS.md（缓存模式）

预定义函数

`efficiency_scorer.py`

根据以下内容计算Navigator效率分数（0-100）：

令牌节省（40分）
缓存效率（30分）
上下文使用（30分）

用法：

python3 skills/nav-stats/functions/efficiency_scorer.py \
  --tokens-saved-percent 92 \
  --cache-efficiency 100 \
  --context-usage 35

输出：94（整数分数）

`report_formatter.py`

将效率指标格式化为视觉化、可分享的报告。

用法：

python3 skills/nav-stats/functions/report_formatter.py \
  --baseline 150000 \
  --loaded 12000 \
  --saved 138000 \
  --savings-percent 92 \
  --cache-efficiency 100 \
  --context-usage 35 \
  --efficiency-score 94 \
  --time-saved 42

输出：格式化的ASCII报告（见第4步）

哲学整合

上下文工程原则：测量验证优化

来自.agent/philosophy/PATTERNS.md：

“测量以验证。Navigator跟踪实际指标，而不是估计。”

这个技能证明：

令牌节省是真实的（基线比较）
缓存效率有效（OpenTelemetry数据）
上下文使用健康（窗口不过载）
节省的时间可量化（每1k令牌6秒）

用户体验

用户说：“显示我的统计数据”

技能显示：

视觉效率报告
清晰的指标（令牌，缓存，上下文）
解释（“这意味着什么”）
可操作的建议

用户可以：

截取屏幕截图并分享（#ContextEfficiency）
了解Navigator的影响
根据建议优化工作流程
验证上下文工程原则

示例输出场景

场景1：出色的效率（分数94）

用户遵循延迟加载模式，缓存完美工作：

92%令牌节省✅
100%缓存效率✅
35%上下文使用✅
分数：94/100

建议：继续保持！分享您的效率。

场景2：公平效率（分数72）

用户一开始就加载了太多文档：

65%令牌节省⚠️
95%缓存效率✅
55%上下文使用✅
分数：72/100

建议：审查延迟加载策略。按需加载文档。

场景3：效率低下（分数48）

用户未使用Navigator模式：

45%令牌节省❌
70%缓存效率⚠️
85%上下文使用❌
分数：48/100

建议：阅读哲学文档。考虑/nav:compact。审查CLAUDE.md。

成功指标

使用此技能后，用户应该：

了解他们的效率分数
看到量化的令牌节省
知道需要改进的地方（如果有的话）
感到有动力分享结果

长期影响：

用户截取报告并分享
"Navigator为我节省了138k令牌"变得常见
效率变得可见，而不是抽象
通过测量实现持续改进

这项技能使Navigator的价值有形且可分享。