harness-context-clear

name	harness-context-clear
description	智能上下文清除技能，基于多维度判断决定是否清除上下文
trigger_words	["clear context","清除上下文","context overflow","session handoff"]
priority	HIGH
dependencies	["harness-config"]
version	v1.0.0

harness-context-clear 智能上下文清除技能

核心能力

1. 读取配置清除阈值
2. 计算 Token 使用率
3. 评估任务复杂度
4. 检查累计任务数
5. 计算错误率
6. 多维度综合判断
7. 生成清除决策报告

判断逻辑

采用多维度投票机制，任一维度达到阈值即触发清除：

因素 1: Token 使用率（权重最高）

触发条件: Token 使用率 ≥ token_threshold（默认 60%）

计算方式:

# 从 Claude API 响应中获取
current_tokens = {当前使用的 tokens}
max_tokens = {最大容量}
usage_rate = (current_tokens / max_tokens) * 100

if [ $usage_rate -ge $TOKEN_THRESHOLD ]; then
  echo "HIGH: Token使用率 ${usage_rate}% 超过阈值 ${TOKEN_THRESHOLD}%"
  TRIGGER_CLEAR=true
fi

说明:

• 这是最直接的指标，反映当前上下文负载
• 默认阈值 60%，可根据项目复杂度调整
• 激进策略: 50%（更频繁清除，适合复杂项目）
• 宽松策略: 70%（减少清除频率，适合简单项目）

因素 2: 任务复杂度（关键指标）

触发条件: 最近任务的复杂度评分 ≥ task_complexity_threshold（默认 6）

复杂度评分标准（1-10分）:

分数	任务类型	典型特征
1-2	极简单任务	修改文档、修复typo、调整配置
3-5	简单任务	添加字段、修复简单bug、小型重构
6-7	中等复杂任务	新增功能、重构模块、集成单个外部服务
8-9	复杂任务	架构调整、性能优化、多系统集成
10	极复杂任务	核心架构重构、安全漏洞修复

评分维度:

# 基础分
score=1

# 代码修改量（+0-3分）
lines_changed=$(git diff --shortstat | grep -o '[0-9]* insertion' | grep -o '[0-9]*')
if [ $lines_changed -gt 100 ]; then
  score=$((score + 3))
elif [ $lines_changed -gt 50 ]; then
  score=$((score + 2))
elif [ $lines_changed -gt 10 ]; then
  score=$((score + 1))
fi

# 涉及文件数（+0-2分）
files_changed=$(git diff --name-only | wc -l)
if [ $files_changed -gt 5 ]; then
  score=$((score + 2))
elif [ $files_changed -gt 2 ]; then
  score=$((score + 1))
fi

# 是否涉及架构变更（+3分）
if grep -q "architecture\|refactor\|redesign" .EnjoyHarness/EVENT_LOG.md; then
  score=$((score + 3))
fi

# 是否有复杂依赖（+2分）
if grep -q "dependency\|integration\|external" .EnjoyHarness/EVENT_LOG.md; then
  score=$((score + 2))
fi

# 是否需要外部系统集成（+2分）
if grep -q "API\|external service\|third-party" .EnjoyHarness/EVENT_LOG.md; then
  score=$((score + 2))
fi

# 上限为10
if [ $score -gt 10 ]; then
  score=10
fi

echo "任务复杂度评分: $score/10"

说明:

• 复杂任务会快速消耗上下文，建议及时清除
• 评分 ≥ 6 的任务属于中高复杂度，需要特别注意

因素 3: 累计任务数（兜底保障）

触发条件: 累计任务数 ≥ consecutive_tasks_limit（默认 5）

计算方式:

# 从 GLOBAL_STATE.md 读取
completed_tasks=$(grep "^completed_tasks:" .EnjoyHarness/GLOBAL_STATE.md | awk '{print $2}')

if [ $completed_tasks -ge $CONSECUTIVE_LIMIT ]; then
  echo "MEDIUM: 累计任务数 ${completed_tasks} 达到阈值 ${CONSECUTIVE_LIMIT}"
  TRIGGER_CLEAR=true
fi

说明:

• 即使其他指标正常，达到此数值也必须清除
• 防止上下文无限累积

因素 4: 错误率（质量指标）

触发条件: 最近5个任务的错误率 > error_rate_threshold（默认 30%）

计算方式:

# 从 ERROR_TRACE.md 读取最近错误
recent_errors=$(tail -n 50 .EnjoyHarness/ERROR_TRACE.md | grep -c "ERROR")
total_tasks=5
error_rate=$((recent_errors * 100 / total_tasks))

if [ $error_rate -gt $ERROR_RATE_THRESHOLD ]; then
  echo "HIGH: 错误率 ${error_rate}% 超过阈值 ${ERROR_RATE_THRESHOLD}%"
  TRIGGER_CLEAR=true
fi

说明:

• 高错误率表明上下文质量下降，需要清除重新开始
• 默认阈值 30%，可根据项目容错度调整

因素 5: 绝对上限（安全边界）

触发条件: 累计任务数 ≥ absolute_limit（默认 10）

计算方式:

if [ $completed_tasks -ge $ABSOLUTE_LIMIT ]; then
  echo "CRITICAL: 累计任务数 ${completed_tasks} 达到绝对上限 ${ABSOLUTE_LIMIT}"
  TRIGGER_CLEAR=true
fi

说明:

• 最后的保障，防止极端情况
• 无论其他条件如何，达到此数必清除

执行步骤

Step 1: 读取配置文件

使用 Bash 工具执行：

CONFIG_FILE=".EnjoyHarness/CONFIG.md"

if [ ! -f "$CONFIG_FILE" ]; then
  echo "❌ 错误: 配置文件不存在"
  echo "请先运行 harness-config 技能"
  exit 1
fi

# 读取核心配置
CLAUDE_CMD=$(grep "^claude_command:" "$CONFIG_FILE" | sed 's/claude_command: *//' | tr -d '"' | tr -d "'")
TASKS_LIMIT=$(grep "^tasks_per_session:" "$CONFIG_FILE" | sed 's/tasks_per_session: *//')

# 读取高级配置（使用默认值）
TOKEN_THRESHOLD=$(grep "^token_threshold:" "$CONFIG_FILE" | sed 's/token_threshold: *//' | tr -d '%' || echo "60")
TASK_COMPLEXITY=$(grep "^task_complexity_threshold:" "$CONFIG_FILE" | sed 's/task_complexity_threshold: *//' || echo "6")
CONSECUTIVE_LIMIT=$(grep "^consecutive_tasks_limit:" "$CONFIG_FILE" | sed 's/consecutive_tasks_limit: *//' || echo "5")
ERROR_RATE_THRESHOLD=$(grep "^error_rate_threshold:" "$CONFIG_FILE" | sed 's/error_rate_threshold: *//' | tr -d '%' || echo "30")
ABSOLUTE_LIMIT=$(grep "^absolute_limit:" "$CONFIG_FILE" | sed 's/absolute_limit: *//' || echo "10")

echo "✅ 配置读取完成"

Step 2: 评估 Token 使用率

注意: Claude Code CLI 不直接暴露 Token 使用情况，需要从 API 层面获取。

替代方案：使用会话时长估算：

# 从 EVENT_LOG.md 计算会话时长
session_start=$(head -n 1 .EnjoyHarness/EVENT_LOG.md | grep -o '\[.*\]' | tr -d '[]')
session_end=$(date '+%Y-%m-%d %H:%M:%S')

# 转换为秒数
start_seconds=$(date -j -f "%Y-%m-%d %H:%M:%S" "$session_start" "+%s" 2>/dev/null || echo "0")
end_seconds=$(date -j -f "%Y-%m-%d %H:%M:%S" "$session_end" "+%s")

duration_seconds=$((end_seconds - start_seconds))
duration_minutes=$((duration_seconds / 60))

# 估算 Token 使用率（假设每分钟消耗 1% 容量）
estimated_token_usage=$((duration_minutes * 1))

echo "会话时长: ${duration_minutes} 分钟"
echo "估算 Token 使用率: ${estimated_token_usage}%"

if [ $estimated_token_usage -ge $TOKEN_THRESHOLD ]; then
  echo "⚠️ Token 使用率可能超过阈值"
  TRIGGER_CLEAR=true
  CLEAR_REASON="Token 使用率估算: ${estimated_token_usage}%"
fi

Step 3: 评估任务复杂度

# 读取最近任务记录
last_task=$(tail -n 20 .EnjoyHarness/EVENT_LOG.md | grep "任务完成" | tail -n 1)

if [ -n "$last_task" ]; then
  # 分析复杂度（简化版本）
  # 实际实现需要根据具体任务内容评分

  # 基于文件修改数量估算
  recent_files=$(git diff --name-only HEAD~1 HEAD 2>/dev/null | wc -l || echo "0")

  if [ $recent_files -ge 5 ]; then
    complexity=8
  elif [ $recent_files -ge 3 ]; then
    complexity=6
  elif [ $recent_files -ge 1 ]; then
    complexity=4
  else
    complexity=2
  fi

  echo "最近任务复杂度: ${complexity}/10"

  if [ $complexity -ge $TASK_COMPLEXITY ]; then
    echo "⚠️ 任务复杂度超过阈值"
    TRIGGER_CLEAR=true
    CLEAR_REASON="任务复杂度: ${complexity}/10"
  fi
fi

Step 4: 检查累计任务数

# 从 GLOBAL_STATE.md 读取
if [ -f ".EnjoyHarness/GLOBAL_STATE.md" ]; then
  completed_tasks=$(grep "^completed_tasks:" .EnjoyHarness/GLOBAL_STATE.md | awk '{print $2}' || echo "0")

  echo "累计完成任务数: ${completed_tasks}"

  # 检查连续任务上限
  if [ $completed_tasks -ge $CONSECUTIVE_LIMIT ]; then
    echo "⚠️ 累计任务数达到连续上限"
    TRIGGER_CLEAR=true
    CLEAR_REASON="累计任务数: ${completed_tasks}/${CONSECUTIVE_LIMIT}"
  fi

  # 检查绝对上限
  if [ $completed_tasks -ge $ABSOLUTE_LIMIT ]; then
    echo "⚠️ 累计任务数达到绝对上限"
    TRIGGER_CLEAR=true
    CLEAR_REASON="达到绝对上限: ${completed_tasks}/${ABSOLUTE_LIMIT}"
  fi
fi

Step 5: 计算错误率

# 从 ERROR_TRACE.md 读取
if [ -f ".EnjoyHarness/ERROR_TRACE.md" ]; then
  recent_errors=$(tail -n 50 .EnjoyHarness/ERROR_TRACE.md | grep -c "ERROR" || echo "0")

  # 计算最近5个任务的错误率
  error_rate=$((recent_errors * 100 / 5))

  echo "最近错误数: ${recent_errors}"
  echo "错误率: ${error_rate}%"

  if [ $error_rate -gt $ERROR_RATE_THRESHOLD ]; then
    echo "⚠️ 错误率超过阈值"
    TRIGGER_CLEAR=true
    CLEAR_REASON="错误率: ${error_rate}%"
  fi
fi

Step 6: 综合判断

echo ""
echo "=== 上下文清除决策 ==="

if [ "$TRIGGER_CLEAR" = true ]; then
  echo "✅ 决策: 建议清除上下文"
  echo "原因: $CLEAR_REASON"
  echo ""

  # 生成清除决策报告
  cat > .EnjoyHarness/CONTEXT_CLEAR_DECISION.md <<EOF
---
timestamp: $(date '+%Y-%m-%d %H:%M:%S')
decision: CLEAR_REQUIRED
reason: $CLEAR_REASON
---

# 上下文清除决策报告

## 决策时间
$(date '+%Y-%m-%d %H:%M:%S')

## 决策结果
✅ **建议清除上下文**

## 触发原因
$CLEAR_REASON

## 详细分析

### Token 使用率
- 估算值: ${estimated_token_usage}%
- 阈值: ${TOKEN_THRESHOLD}%
- 状态: $([ $estimated_token_usage -ge $TOKEN_THRESHOLD ] && echo "超过阈值 ⚠️" || echo "正常 ✅")

### 任务复杂度
- 评分: ${complexity}/10
- 阈值: ${TASK_COMPLEXITY}
- 状态: $([ $complexity -ge $TASK_COMPLEXITY ] && echo "超过阈值 ⚠️" || echo "正常 ✅")

### 累计任务数
- 数量: ${completed_tasks}
- 连续上限: ${CONSECUTIVE_LIMIT}
- 绝对上限: ${ABSOLUTE_LIMIT}
- 状态: $([ $completed_tasks -ge $CONSECUTIVE_LIMIT ] && echo "达到上限 ⚠️" || echo "正常 ✅")

### 错误率
- 错误率: ${error_rate}%
- 阈值: ${ERROR_RATE_THRESHOLD}%
- 状态: $([ $error_rate -gt $ERROR_RATE_THRESHOLD ] && echo "超过阈值 ⚠️" || echo "正常 ✅")

## 建议操作
1. 执行会话交接: harness-session-handoff
2. 清除当前会话上下文
3. 启动新会话继续任务
EOF

  echo "📁 详细报告: .EnjoyHarness/CONTEXT_CLEAR_DECISION.md"

else
  echo "❌ 决策: 无需清除上下文"
  echo "当前上下文状态健康"

  # 生成健康报告
  cat > .EnjoyHarness/CONTEXT_HEALTH_REPORT.md <<EOF
---
timestamp: $(date '+%Y-%m-%d %H:%M:%S')
decision: NO_CLEAR_REQUIRED
---

# 上下文健康报告

## 检查时间
$(date '+%Y-%m-%d %H:%M:%S')

## 检查结果
✅ **上下文状态健康**

## 详细分析

### Token 使用率
- 估算值: ${estimated_token_usage}%
- 阈值: ${TOKEN_THRESHOLD}%
- 状态: 正常 ✅

### 任务复杂度
- 评分: ${complexity}/10
- 阈值: ${TASK_COMPLEXITY}
- 状态: 正常 ✅

### 累计任务数
- 数量: ${completed_tasks}
- 连续上限: ${CONSECUTIVE_LIMIT}
- 绝对上限: ${ABSOLUTE_LIMIT}
- 状态: 正常 ✅

### 错误率
- 错误率: ${error_rate}%
- 阈值: ${ERROR_RATE_THRESHOLD}%
- 状态: 正常 ✅

## 建议
继续当前会话，无需清除上下文。
EOF

  echo "📁 健康报告: .EnjoyHarness/CONTEXT_HEALTH_REPORT.md"
fi

Step 7: 触发会话交接（如果需要）

if [ "$TRIGGER_CLEAR" = true ]; then
  echo ""
  echo "准备触发会话交接..."

  # 调用 harness-session-handoff 技能
  # （实际实现需要等待 harness-session-handoff 技能完成）

  echo "💡 请执行: harness-session-handoff"
  echo "或等待自动触发机制"
fi

成功标准

• 成功读取所有配置阈值
• Token 使用率估算准确
• 任务复杂度评分合理
• 累计任务数统计准确
• 错误率计算准确
• 判断结果有详细理由
• 生成决策报告或健康报告

失败处理

失败场景 1: 配置文件缺失

处理: 提示用户运行 harness-config 技能

失败场景 2: 状态文件缺失

处理: 使用默认值继续，记录警告

失败场景 3: Git 历史不足

处理: 跳过复杂度评估，使用其他维度判断

使用示例

示例 1: Token 使用率过高

输入: 会话已运行 90 分钟

AI 执行:
✅ 配置读取完成
会话时长: 90 分钟
估算 Token 使用率: 90%

⚠️ Token 使用率可能超过阈值

=== 上下文清除决策 ===
✅ 决策: 建议清除上下文
原因: Token 使用率估算: 90%

📁 详细报告: .EnjoyHarness/CONTEXT_CLEAR_DECISION.md

示例 2: 任务复杂度过高

输入: 刚完成一个涉及 8 个文件的架构重构

AI 执行:
✅ 配置读取完成
最近任务复杂度: 9/10

⚠️ 任务复杂度超过阈值

=== 上下文清除决策 ===
✅ 决策: 建议清除上下文
原因: 任务复杂度: 9/10

📁 详细报告: .EnjoyHarness/CONTEXT_CLEAR_DECISION.md

示例 3: 上下文健康

输入: 刚完成第 2 个简单任务

AI 执行:
✅ 配置读取完成
会话时长: 15 分钟
估算 Token 使用率: 15%
最近任务复杂度: 3/10
累计完成任务数: 2
错误率: 0%

=== 上下文清除决策 ===
❌ 决策: 无需清除上下文
当前上下文状态健康

📁 健康报告: .EnjoyHarness/CONTEXT_HEALTH_REPORT.md

关系图

harness-config (提供配置)
    ↓
harness-context-clear (本技能)
    ↓
harness-session-handoff (触发会话交接)

注意事项

1. Token 使用率: 由于 Claude Code CLI 不直接暴露 Token 信息，使用会话时长估算，仅供参考
2. 任务复杂度: 当前实现基于文件修改数量简化估算，实际部署时需要更精细的评分逻辑
3. 错误率: 需要 ERROR_TRACE.md 文件支持，建议配合错误追踪机制使用
4. 多维度判断: 任一维度达到阈值即触发清除，采用"或"逻辑而非"与"逻辑
5. 自动触发: 建议在守护进程或钩子中定期调用本技能，实现自动判断