# Harness Context Clear

> 智能上下文清除技能，基于多维度判断决定是否清除上下文

- Skill: `konglong87/harness-context-clear` (Agent Skill)
- Install (CLI): `npx skillmds@latest add konglong87/harness-context-clear`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-context-clear/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-context-clear

---


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

## 核心能力

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

## 判断逻辑

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

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

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

**计算方式**:
```bash
# 从 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 | 极复杂任务 | 核心架构重构、安全漏洞修复 |

**评分维度**:
```bash
# 基础分
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）

**计算方式**:
```bash
# 从 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%）

**计算方式**:
```bash
# 从 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）

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

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

## 执行步骤

### Step 1: 读取配置文件

使用 Bash 工具执行：

```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 层面获取。

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

```bash
# 从 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: 评估任务复杂度

```bash
# 读取最近任务记录
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: 检查累计任务数

```bash
# 从 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: 计算错误率

```bash
# 从 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: 综合判断

```bash
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: 触发会话交接（如果需要）

```bash
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. **自动触发**: 建议在守护进程或钩子中定期调用本技能，实现自动判断