mcpField
F
friction-detector

friction-detector

github.com/atholaAgent 工作流34374 次安装1 天前更新
代码仓库

关于 friction-detector

friction-detector 用于在 Claude Code 会话中识别并追踪执行摩擦，将反复出现的问题逐步整理为持久指导。它通过分级存储和评分提出升级建议，不会自动修改 CLAUDE.md。

主要功能

  1. 01识别纠正、失败、拒绝和重试等信号
  2. 02跨会话记录并按时间衰减评分
  3. 03将重复模式整理到 LEARNINGS.md
  4. 04升级到 CLAUDE.md 前征求明确批准

适用场景

  1. 01生成会话结束时的摩擦报告
  2. 02发现多次出现的命令失败或重试循环
  3. 03根据证据提出持久指导更新

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/athola/claude-night-market --skill friction-detector

安装后在 Claude Code 中输入/friction-detector确认已加载。

详细介绍

摩擦到学习流水线

概述

在 Agent 执行期间检测摩擦信号，跨会话跟踪这些信号， 并将反复出现的模式升级为永久指导。弥合短暂的会话摩擦 与持久的 CLAUDE.md 规则之间的差距。

研究依据：Claude Coach（基于钩子的摩擦检测与 SQLite 存储）、alirezarezvani 的 self-improving-agent（将三级 MEMORY 升级到 CLAUDE.md）以及 ACE 框架（arXiv：根据执行反馈不断改进操作手册， 在 Agent 任务上的表现提升了 10.6%）。

当前缺口：LEARNINGS.md 已存在，但需要通过 /abstract:aggregate-logs 手动汇总。此技能新增自动摩擦检测和 结构化的提升路径。

摩擦信号类型

信号检测方法权重
反复纠正用户在会话中 2 次或更多次覆盖同一工具调用高
命令失败退出代码 != 0 的模式（同类型命令反复失败）中
权限拒绝用户拒绝工具调用，表明行为出乎预期高
重新读取会话中读取同一文件 3 次或更多次（上下文丢失）低
重试循环同一操作以不同方式尝试 3 次或更多次中
用户不满明确的负面反馈或纠正性措辞高

权重评分：高 = 3，中 = 2，低 = 1 分 （每次发生）。加权分数决定提升 速度。

三级存储提升

Tier 1: Friction Log (ephemeral, per-session)
  Location: ~/.claude/friction/sessions/{date}-{id}.json
  Retention: 30 days, then pruned
  Threshold: 1 occurrence, logged, no action

Tier 2: Pattern Candidate (persistent, LEARNINGS.md)
  Location: ~/.claude/skills/LEARNINGS.md (friction section)
  Threshold: 3+ occurrences across 2+ sessions
  Action: flagged for review in next friction report

Tier 3: Graduated Rule (CLAUDE.md or skill update)
  Threshold: reviewed + user-approved
  Action: permanent guidance added to project/user config
  Constraint: NEVER auto-modify CLAUDE.md
提升公式
graduation_score = (weighted_count * recency_factor) / sessions_seen

recency_factor:
  last 7 days  = 1.0
  8-14 days    = 0.7
  15-30 days   = 0.4
  31+ days     = 0.1

Tier 2 threshold: graduation_score >= 6.0
Tier 3 proposal:  graduation_score >= 12.0

检测工作流

在会话结束时、上下文使用率达到 80% 时（通过 conserve:clear-context），或改进周期失败后运行 （当 abstract:metacognitive-self-mod 检测到 性能回退时）。

步骤 1：扫描会话中的信号

对于发现的每个摩擦指标，将其封装在共享的会话捕获信封（ADR-0011）中， 使下游读取方可以通过一个解析器摄取摩擦信号和 轨迹捕获条目：

{
  "schema_version": "session-capture/1",
  "session_id": "2026-04-14-abc12345",
  "timestamp": "2026-04-14T10:23:00Z",
  "source": "friction-detector",
  "payload": {
    "signal_type": "retry_loop",
    "description": "rg command failed 3x, fell back to grep",
    "context": "searching for pattern in node_modules",
    "weight": "medium"
  }
}

采用信封格式之前写入的旧文件会被读取为 session-capture/0（将整个文件视为有效载荷）。有关契约和迁移路径，请参阅 docs/adr/0011-session-capture-envelope.md。

步骤 2：与现有日志比较
FRICTION_DIR=~/.claude/friction/sessions
mkdir -p "$FRICTION_DIR"

# Count prior occurrences of similar signals
if command -v rg &>/dev/null; then
  rg -c "$SIGNAL_TYPE" "$FRICTION_DIR"/*.json 2>/dev/null || echo "0"
else
  grep -rc "$SIGNAL_TYPE" "$FRICTION_DIR"/*.json 2>/dev/null || echo "0"
fi
步骤 3：计算提升分数

汇总各会话日志：加总加权发生次数， 应用近期衰减，除以会话数，并与 各层级阈值进行比较。

步骤 4：提出提升建议

达到第 2 层阈值：将其追加到 LEARNINGS.md 的摩擦部分。 达到第 3 层阈值：向用户展示带有证据的提案， 在进行任何修改前等待明确批准。

步骤 5：存储结果

将会话日志写入 ~/.claude/friction/sessions/{date}-{session_id}.json 并更新 ~/.claude/friction/index.json。

降噪规则

忽略以下信号：

  1. 一次性故障：暂时性的网络或 CI 错误 （除非重复发生 3 次或更多次）
  2. 用户主动探索：有意进行的实验不属于 Agent 错误
  3. 已提升的模式：现有 CLAUDE.md 规则或技能说明已涵盖的模式
  4. 外部工具故障：与 Agent 行为无关的 MCP 服务崩溃和 类似工具错误

衰减系数：超过 30 天的信号仅计入其原始权重的 10%（参见提升公式中的 recency_factor）。

摩擦报告格式

## Friction Report: Session {date}

### New Signals (Tier 1)
- [RETRY] `rg` command failed 3x, fell back to `grep`
- [RE-READ] Read SKILL.md 4 times (lost file structure context)

### Recurring Patterns (Tier 2 candidates)
- [CORRECTION] User corrected file path format 4x across 3 sessions
  Score: 8.4 (threshold: 6.0)
  Candidate: Add path format guidance to CLAUDE.md

### Graduation Proposals (Tier 3)
- [RULE] "Always use absolute paths in Read tool"
  Evidence: 7 corrections across 5 sessions
  Score: 14.2 (threshold: 12.0)
  Action: Approve / Reject / Defer

### Noise Filtered
- 2 transient network timeouts (ignored)
- 1 user-initiated deep exploration (ignored)

集成

提供给：LEARNINGS.md（第 2 层模式，格式与 /abstract:aggregate-logs 相同）、 abstract:skill-improver（优先级评分）以及 abstract:metacognitive-self-mod（流水线 有效性）。

读取自：会话记录、 aggregate_learnings_daily 钩子数据，以及用于趋势关联的 性能跟踪器。

不适用场景

  • 单次孤立故障（等待再次发生）
  • 技能编写（使用 abstract:skill-authoring）
  • 常规日志汇总（使用 /abstract:aggregate-logs）

相关内容

  • abstract:metacognitive-self-mod：改进分析
  • abstract:skills-eval：评估标准
  • /abstract:aggregate-logs：手动生成 LEARNINGS.md
  • conserve:clear-context：在 80% 时触发摩擦扫描

退出标准

  • 已按照“摩擦报告格式”生成会话摩擦报告， 且至少填充了一个部分（新信号、重复模式 或晋升提案）
  • 每个信号都按照 session-capture/1 架构，以 JSON 格式写入 ~/.claude/friction/sessions/{date}-{session_id}.json
  • graduation_score >= 12.0 的模式会生成 Tier 3 提案；技能不会自动修改 CLAUDE.md
  • 噪声信号（网络故障、用户探索）会显示在 “已过滤的噪声”中，并从晋升评分中排除

评论

支持 Markdown