⚡

上下文条目整合 ctx-consolidate

这是一个用于软件开发项目中知识管理的技能。它专门用于分析并整合LEARNINGS.md（学习记录）和DECISIONS.md（决策记录）文件中内容重叠或冗余的条目。通过关键词匹配识别相似条目，在用户批准后，将多个条目合并为一个更精炼的条目，同时将原始条目完整归档，确保项目上下文文件保持精简、有序且信息不丢失。关键词：上下文管理、知识管理、文档整合、冗余消除、DevOps工具、项目维护。

DevOps 0 次安装 0 次浏览 更新于 2/27/2026

name: ctx-consolidate description: “整合LEARNINGS.md或DECISIONS.md中的冗余条目。当ctx drift报告条目数量过高或条目重叠时使用。” allowed-tools: Bash(ctx:*), Read, Edit, Write

分析LEARNINGS.md和/或DECISIONS.md中的条目，按主题对重叠条目进行分组，并在用户批准后，将各组合并为更紧凑的整合条目。原始条目会被归档，而非删除。

关键区别

整合 ≠ 归档。 归档是将旧条目移动到.context/archive/。整合则是用更紧凑的条目替换冗长的条目——文件保持可用，只是更精简。原始条目会作为记录移动到归档中。

使用时机

  • 当ctx drift报告条目数量超过阈值时（默认：30个学习条目，20个决策条目）
  • 当你注意到有3个或更多关于同一主题的条目时
  • 当用户要求“清理学习记录”、“整合上下文”或“减少决策中的噪音”时
  • 在发布前，以保持上下文简洁

不应使用的时机

  • 当条目少于10个时（没有有意义的条目可以分组）
  • 当用户想要删除条目时（应提供归档作为替代方案）
  • 自动执行——在修改文件前始终需要用户批准
  • 在用户专注于交付任务的中途

执行步骤

步骤1：解析条目

读取目标文件：

# 首先检查条目数量
ctx drift --json

然后直接读取文件：

  • .context/LEARNINGS.md
  • .context/DECISIONS.md

通过## [YYYY-MM-DD-HHMMSS] 标题格式的标题解析条目。每个条目从其标题开始，延伸到下一个标题或文件结束前的行。

步骤2：提取关键词并分组

为每个条目从其标题和正文中提取关键词：

  1. 按空格和标点符号分割文本
  2. 将所有内容转换为小写
  3. 过滤掉停用词（the, and, for, with, from, are, was等）和少于3个字符的单词
  4. 去重

构建关键词到条目的映射。共享2个或更多非平凡关键词的条目是同一分组的候选对象。

分组规则：

  • 最小分组大小：2个条目（单个条目无法整合）
  • 最大分组大小：8个条目（更大的分组表明主题需要拆分，而非合并）
  • 一个条目只能属于一个分组（分配到最佳匹配）

步骤3：展示候选分组

向用户展示发现的结果。格式：

LEARNINGS.md的整合候选分组：

分组1："Hook行为"（5个条目）
  - [2026-01-15] Hook脚本可能丢失执行权限
  - [2026-01-20] 两级Hook输出足够
  - [2026-02-03] Claude Code Hook键名
  - [2026-02-09] Agent忽略重复的Hook输出
  - [2026-02-16] 迁移后安全文档易受攻击
  -> 建议：合并为1个整合条目

分组2："路径处理"（3个条目）
  - [2026-01-10] 路径构建使用标准库
  - [2026-02-05] G304 gosec误报
  - [2026-02-16] gosec G301/G306权限
  -> 建议：合并为1个整合条目

未分组：12个条目（无需整合）

等待用户批准、修改或拒绝每个分组。 未经明确确认，请勿继续。

步骤4：生成整合条目

对于每个批准的分组，编写一个整合条目，该条目：

  • 使用YYYY-MM-DD-HHMMSS格式的当前时间戳
  • 在标题后附加"（已整合）"
  • 在**整合自**行中列出原始条目的日期范围
  • 将每个原始条目提炼为1-2行
  • 保留所有独特信息（不丢失任何信息）

格式：

## [YYYY-MM-DD-HHMMSS] Hook行为（已整合）

**整合自**：5个条目（2026-01-15 至 2026-02-16）

- Hook脚本可能在不发出警告的情况下丢失执行权限；同步操作后始终恢复+x
- 两级输出（stdout用于AI上下文，stderr+exit用于阻塞）足够；不要过度设计严重性级别
- Claude Code Hook键名区分大小写：PreToolUse，而非pre_tool_use
- Agent会产生重复疲劳：在不同调用中变换Hook输出的措辞
- 基础设施迁移后，首先审计安全文档——安全指南中的陈旧路径会带来虚假信心

步骤5：执行批准的合并

对于每个批准的分组：

  1. 添加整合条目到文件顶部（在# Learnings或# Decisions标题下方）
  2. 从源文件中移除原始条目
  3. 将原始条目追加到归档，位于.context/archive/learnings-consolidated-YYYY-MM-DD.md（或decisions-consolidated-YYYY-MM-DD.md）
  4. 重建索引：
ctx reindex learnings
# 或
ctx reindex decisions

步骤6：报告结果

已整合LEARNINGS.md：
  - 分组"Hook行为"：5个条目 -> 1个（原始条目已归档）
  - 分组"路径处理"：3个条目 -> 1个（原始条目已归档）
  总计：8个条目整合为2个。文件条目数从47减少到41。
  归档：.context/archive/learnings-consolidated-2026-02-19.md

归档格式

归档文件使用与源文件相同的Markdown格式。每个归档条目保留其原始时间戳和内容，前面有一个标题，注明哪个整合条目替换了它：

# 已归档的学习记录（整合于2026-02-19）

原始条目已被LEARNINGS.md中的整合条目替换。

## 分组：Hook行为

## [2026-01-15-120000] Hook脚本可能丢失执行权限
（原始内容完全保留）

## [2026-01-20-093000] 两级Hook输出足够
（原始内容完全保留）

此技能不执行的操作

  • 自动整合：始终需要用户批准
  • 跨文件整合：学习记录保留在LEARNINGS.md中，决策保留在DECISIONS.md中
  • 删除条目：始终将原始条目作为记录归档
  • 通过嵌入进行语义理解：使用关键词匹配，这对于具有一致格式的结构化条目已经足够
  • 整合TASKS.md或CONVENTIONS.md：对于任务，使用ctx tasks archive；约定很少需要整合

质量检查清单

在报告结果之前：

  • [ ] 在做出更改前展示了所有候选分组
  • [ ] 等待了用户对每个分组的明确批准
  • [ ] 每个整合条目保留了所有独特信息
  • [ ] 原始条目已归档，未删除
  • [ ] 修改后运行了ctx reindex
  • [ ] 报告了更改内容和归档写入位置