mcpField
L
learning-aggregator

learning-aggregator

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

关于 learning-aggregator

面向维护 Agent 学习记录的团队，汇总 `.learnings/` 中的条目，按模式和复发情况生成排序后的改进候选报告。可选的 `--deep` 模式还会分析 Entire 会话轨迹，并与学习记录合并证据。

主要功能

  1. 01读取并聚合学习记录
  2. 02按 Pattern-Key 去重与分组
  3. 03计算复发次数与任务范围
  4. 04生成排序后的差距报告
  5. 05可选分析 Entire 会话轨迹

适用场景

  1. 01定期检查反复出现的 Agent 问题
  2. 02在重大任务前查找相关历史模式
  3. 03为指令改进整理有证据的候选项
  4. 04从会话轨迹中识别重试与用户纠正

安装

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

$npx skills add https://github.com/pskoett/pskoett-ai-skills --skill learning-aggregator

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

附带文件evals/evals.json

详细介绍

学习汇总器

读取所有会话中累积的 .learnings/ 文件，查找规律，并生成按优先级排序的晋升候选项列表。这是外层循环的 检查 步骤。

没有此技能，.learnings/ 就只是一个只写日志。规律不断累积，却无人归纳。由于没人查看，两周后同样的问题又会出现。

使用时机

  • 每周例行 — 按计划或手动审查累积的学习记录
  • 执行重要任务前 — 检查该任务领域是否已有已知规律
  • 一系列会话结束后 — 汇总一个冲刺或事件中的发现
  • 某条记录的 Recurrence-Count 达到晋升阈值（>= 3）时 — 结合完整上下文核实候选项

输出内容

一份 差距报告 — 按优先级排列的规律列表，这些规律已达到（或接近）晋升阈值，并附有证据和建议操作。

步骤 1：读取所有学习记录文件

读取 .learnings/ 中的这些文件：

文件内容
LEARNINGS.md更正、知识缺口、最佳实践、反复出现的规律
ERRORS.md命令失败、API 错误、异常
FEATURE_REQUESTS.md缺失的功能
HEALS.md由 self-healing 记录的已验证运行时恢复——包括标记出已具备晋升条件的重复规律的 Handoff 块

解析每条记录的元数据：

  • Pattern-Key — 稳定的去重键
  • Recurrence-Count — 该规律出现的次数
  • First-Seen / Last-Seen — 日期范围
  • Priority — 低 / 中 / 高 / 严重
  • Status — 待处理 / 进行中 / 已解决 / 不予修复 / 已晋升 / 已晋升为技能（记录者使用的术语；晋升就绪状态根据 Recurrence-Count 计算，不作为状态存储）
  • Area — 前端 / 后端 / 基础设施 / 测试 / 文档 / 配置
  • Related Files — 受影响的代码库部分
  • Source — 对话 / 错误 / 用户反馈 / simplify-and-harden
  • Tags — 自由格式标签
  • Task-ID、Session-ID、Occurrence-ID、Source-Ref、Copied-From — 较新记录者使用的可选来源字段

第 2 步：分组与汇总

先构建规范化的发生记录，再进行分组：

  1. 即使相同条目出现在多个仓库位置，也要合并具有相同条目 ID 和规范化内容的副本。
  2. 合并在 .learnings/、云端／本地镜像、分叉仓库、转发的转录记录和追踪来源中匹配的 Occurrence-ID 值。
  3. 若缺少 Occurrence-ID，则使用明确的 Task-ID、Session-ID、Source-Ref 和 Copied-From 血缘信息以及规范化证据来识别副本。不要仅凭不同的文件路径或检查点 ID 推断它们相互独立。
  4. 将描述同一任务发生记录的一条 .learnings 条目和一个追踪事件视为同一次发生，同时保留两者的来源引用作为佐证。
  5. 对于缺少稳定任务／会话溯源信息的旧条目，将血缘标记为 unknown。这些条目可以按每个规范化条目一次的频率计入其声明的复发次数，但所有血缘未知的证据合计最多只能算作一项独立任务，且不能单独证明跨任务阈值已达成。

然后按 Pattern-Key 对规范化发生记录分组。对于每个组：

  1. 统计去重后的复发次数，以规范化发生记录为准。不要累加同一条目的重复副本的 Recurrence-Count。
  2. 统计不同任务数，依据稳定的任务／会话血缘，而非源文件数量。
  3. 计算时间窗口——First-Seen 与 Last-Seen 之间的天数。
  4. 收集所有相关文件——合并所有条目的文件引用。
  5. 取组内最高优先级。
  6. 收集证据——每个条目的 Summary 和 Details。

对于没有 Pattern-Key 的条目，仅使用保守的分组方式：

  • 完全匹配：Area 相同，且至少有 2 个相同的 Tags。
  • 文件重叠：Related Files 路径相同（路径必须完全匹配，不能使用子字符串匹配）。
  • 不要基于 Summary 文本进行模糊匹配——错误分组的危害大于不分组。

将未分组的条目单独标出，并建议为其指定 Pattern-Key。未分组条目很常见，也在预期之内——它们可能是一次性问题，也可能是真正新颖的问题。

第 3 步：排序与分类

晋升阈值

当满足以下条件时，条目已具备晋升条件：

  • 该组的 Recurrence-Count >= 3。
  • 有稳定溯源信息证明其出现在 >= 2 项不同任务中。
  • 时间窗口不超过 30 天。

状态属于晋升状态的一部分，而不仅仅是显示元数据：

  • promoted、promoted_to_skill、resolved 和 wont_fix 对已记录的发生记录而言是终态。保留这些状态作为历史记录，但不要将仅包含终态记录的组列为具备晋升条件。
  • 如果在最近一次终态事件之后出现更新的 pending 或 in_progress 发生记录，则将其归类为回归／重新出现的模式，并根据终态之后的发生记录计算是否具备晋升条件。
  • Handoff 区块只能证明此前已达到阈值，不能作为再次晋升已处于终态的模式的许可。
接近阈值

满足以下任一条件时，条目即为接近阈值：

  • Recurrence-Count >= 2；或
  • Priority: high/critical，且至少复发一次。
分类

对于每个晋升候选项，对问题差距类型进行分类：

差距类型表现修复目标
知识差距Agent 不知道 X更新项目指令文件（CLAUDE.md、AGENTS.md、.github/copilot-instructions.md）
工具差距Agent 因缺少相应能力而采用临时变通方案添加或更新 MCP 工具／脚本
技能差距同一行为模式反复失败创建或更新技能（使用 /skill-creator，通过 quick_validate.py 验证，并注册 skill-check 评估）
歧义对规范／提示词存在相互冲突的解释明确指令或添加示例
推理失败Agent 掌握相关知识，但推理错误添加明确的决策规则或约束

第 4 步：生成差距报告

输出结构化报告：

## Learning Aggregator: Gap Report

**Scan date:** YYYY-MM-DD
**Period:** [since date] to [now]
**Entries scanned:** N
**Patterns found:** N
**Promotion-ready:** N
**Approaching threshold:** N

### Promotion-Ready Patterns

#### 1. [Pattern-Key] — [Summary]

- **Recurrence:** N times across M tasks
- **Window:** First-Seen → Last-Seen
- **Priority:** high
- **Gap type:** knowledge gap
- **Area:** backend
- **Related files:** path/to/file.ext
- **Evidence:**
  - [LRN-YYYYMMDD-001] Summary of first occurrence
  - [LRN-YYYYMMDD-002] Summary of second occurrence
  - [ERR-YYYYMMDD-001] Summary of related error
- **Recommended action:** Add rule to project instruction files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md): "[concise prevention rule]"
- **Eval candidate:** Yes — [description of what to test]

#### 2. ...

### Approaching Threshold

#### 1. [Pattern-Key] — [Summary]
- **Recurrence:** 2 times across 1 task
- **Needs:** 1 more recurrence or 1 more distinct task
- ...

### Ungrouped Entries (no Pattern-Key)

- [LRN-YYYYMMDD-005] "Summary" — needs pattern_key assignment
- ...

### Dismissed / Stale

- Entries with Last-Seen > 90 days ago and Status: pending → recommend dismissal
- Terminal-only patterns → report as historical, not promotion-ready
- Legacy groups without enough stable task provenance → report as unverified cross-task recurrence

步骤 5：交接

差距报告将交由：

  1. self-improvement 技能 — 主 Agent 遵循其晋级工作流，重新验证候选项、展示拟议差异，并将经人工批准的规则应用到项目指令文件中。传递 Pattern-Key、证据、复现次数、差距类型、建议操作、相关文件和跟踪器。无需专用的 Agent 预设。
  2. eval-creator 技能 — 接收评估候选项并创建永久测试用例
  3. 人工审查 — 适用于归类为“推理失败”或“歧义”的模式（这些情况需要人工判断）

筛选

  • --since YYYY-MM-DD — 仅扫描此日期之后的条目
  • --min-recurrence N — 提高晋级阈值
  • --area AREA — 筛选特定领域（frontend、backend 等）
  • --deep — 同时通过 Entire 分析会话轨迹（见下文“会话轨迹分析”）

会话轨迹分析

外层循环从两个互补的数据源读取信息：

数据源内容频率成本
.learnings/会话期间由 self-improvement 明确写入的条目。Agent 自身的反思：纠正、知识缺口、它注意到的重复模式。每个会话（热路径）接近零
会话轨迹由 Entire 捕获的完整会话记录：提示词、工具调用、输出、修改的文件、令牌用量、检查点。每周或按需（冷路径）较高 — 仅按计划频率运行

默认模式读取 .learnings/，并根据 Agent 明确记录的内容生成差距报告。--deep 模式还会分析会话轨迹，并合并两个数据源的发现。

为什么两个数据源都很重要

.learnings/ 记录的是 Agent 注意到并选择记录的内容 — 经过筛选的子集。会话轨迹则捕获发生的一切，包括 Agent 绕过、重试或从未意识到是失败的模式。

在轨迹中可见、但在 .learnings/ 中缺失的模式示例：

  • 重试循环：同一工具调用以细微变化重复 3 次以上。Agent 最终成功了，但从未记录最初的失败。
  • 用户未明说的纠正：用户在流程中途说“不了，这不对”。Agent 调整了方向，却没有记录这次误解。
  • 绕过测试失败：测试失败后，Agent 改变了方法，新方法通过了测试，最初的失败也被遗忘了。
  • 上下文交接原因：哪些漂移信号实际触发了交接，而不只是记录发生过交接。
  • 令牌／时间异常：成本相对于输出明显偏高的会话 — 这是 Agent 未察觉的低效信号。

这些模式对外层循环很有价值，因为 Agent 无法自行报告它们。会话轨迹是唯一的数据来源。

何时触发 --deep 模式

轨迹分析不是按会话进行的，而是按计划频率进行：

  • 每周定期运行（建议的最低频率）：在一个冲刺或一系列密集会话之后
  • 事件发生后：出现问题且你想了解原因时
  • 晋级前：在将某个模式提交到项目指令文件之前，确认它确实会在实际会话中重复出现
  • 手动调用：/learning-aggregator --deep --since 7d

每个会话都运行轨迹分析会消耗令牌，却不会产生新的信号 — 跨会话模式只有在多个会话中才会显现。

使用 Entire 读取轨迹

请求 --deep 时，该技能会使用 entire CLI 查询影子分支数据：

# Check availability
entire --version

# List recent checkpoints as JSON (id, date, session_id, message, tool_use_id)
entire rewind --list

# Read a checkpoint's full transcript
entire explain --checkpoint <id> --full --no-pager

# Or raw JSONL
entire explain --checkpoint <id> --raw-transcript --no-pager

# Filter to one session
entire explain --session <session-id-prefix>

# Generate AI summary (expensive, use sparingly)
entire explain --checkpoint <id> --generate

如果未安装 entire、当前仓库未启用 Entire，或者 entire rewind --list 成功运行但返回零个检查点，--deep 将回退到仅使用 .learnings/ 的模式，并在差距报告中说明具体限制。检查点列表为空 并不能证明没有发生过会话。

从追踪记录中提取的内容

对于时间窗口内的每个检查点，解析原始转录记录并查找：

  1. 工具调用重复 — 同一工具搭配相似参数出现 > 3 次 → 可能陷入重试循环。模式键：retry-loop.<tool>
  2. 用户纠正标记 — 用户消息中包含“no”“wrong”“actually”“instead”，且紧接在 Agent 操作之后 → 模式键：correction.<area>
  3. 工具输出中的错误模式 — error、failed、Traceback 等是候选信号，不代表失败的确凿证据；需结合记录的工具状态进行佐证 → 模式键：error.<category>
  4. 交接触发条件 — context-surfing 退出事件，以及触发了哪些偏移信号 → 模式键：drift.<signal>
  5. 方法变更 — Agent 在任务中途切换策略，却没有明确说明转变 → 模式键：approach-switch.<domain>
  6. Token 异常 — Token 数量 > 相似任务类型中位数 2 倍的会话 → 模式键：cost.<task-type>

在可能的情况下，将每条发现归一化为与自我改进相同的分类体系（如 harden.input_validation、simplify.dead_code 等）。保留追踪记录来源、检查点、会话和任务沿袭信息，以便与 .learnings/ 中的证据进行去重。

两种来源如何合并到差距报告中

运行 --deep 时，差距报告中的每个模式都会包含一个 sources 字段：

promotion_ready:
  - pattern_key: "harden.input_validation"
    recurrence_count: 5
    sources:
      - .learnings/LEARNINGS.md (3 entries)
      - entire:traces (5 occurrences across 4 sessions)
    confidence: high  # appears in both sources
    evidence:
      - "LRN-20260401-001: Missing bounds check on pagination"
      - "entire:1ca16f9b: Retry loop on /api/search — pageSize rejected 4 times"
      - "entire:8bf2e4cd: User correction 'validate before DB query'"
    entire_checkpoints:
      - 1ca16f9bb3801ee2a02f2384f31355a54b81ea00
      - 8bf2e4cd63d01040b38df07c43f73e0f15d05ac9

同时出现在两种来源中的模式，比只出现在其中一种来源中的模式可信度更高。只出现在 .learnings/ 中的模式可能是勤勉的 Agent 过度记录所致。只出现在追踪记录中的模式则可能是噪声。重叠部分的信号最强。

追踪记录来源兼容性

默认实现通过 entire rewind --list 和 entire explain 命令支持 Entire（v0.5.4+）。这一概念不依赖具体来源 — 只要环境提供以下内容，也可以使用有文档说明的 Claude、Copilot、Codex 或其他会话来源：

  • 最近检查点的列表（含 id、时间戳、会话 id）
  • 读取检查点转录记录的能力
  • 用于按频率筛选的时间戳

……均可作为追踪记录来源。可以在 scripts/ 中添加其他采集工具的适配器，也可以通过 gh-aw mcp-scripts 添加。

如果没有可用的有文档说明的来源，请勿抓取任意私有转录记录位置，也勿自行臆造适配器。任何适配器都必须输出与 Step 2 相同的稳定任务／会话／来源沿袭信息和出现情况指纹。对于不受支持或为空的来源，应明确报告，而不是将其视为独立证据。

持久化

从工作目录读取 .learnings/。这是唯一的持久化模式 — 此技能在交互式会话中不会集成外部记忆后端。如需在 CI 侧跨工作流运行持久存储，请参阅 learning-aggregator-ci，它可以选择使用 gh-aw 的 repo-memory（Git 分支持久化）作为状态存储。生成的分支是普通 Git 分支，可按需在本地获取，但交互式技能本身只读取本地文件。

差距报告中的跟踪器 ID

差距报告中的每个晋升候选项都包含一个 tracker 字段，其值设为模式键。self-improvement 晋升工作流会在交接信息中保留该字段，并可选择将其作为注释写入项目说明文件；eval-creator 会在评估用例中引用该字段。如需审计已启用的内联来源信息，可在代码库和 GitHub 中搜索 tracker:[pattern-key]。

此技能不会做什么

  • 不会修改 .learnings/ 文件（只读分析）
  • 不会执行晋升（这由需人工审核的 self-improvement 工作流负责）
  • 不会创建评估（这由 eval-creator 负责）
  • 不会修复代码或运行测试
  • 不会替代人工判断来处理含义模糊的模式
  • 不会逐会话运行 --deep 追踪分析 — 只会按频率运行或在明确调用时运行
  • 不要求使用 Entire — 追踪记录来源不可用时，会回退到仅使用 .learnings/ 的模式

评论

支持 Markdown