会话学习技能

双模式学习引擎：分析交互内容，提取有价值的学习并持久化。

两种模式共享同一条处理管线（信号提取 → 四层分类 → 存储探测 → 确认 → 持久化），区别仅在于数据从哪来。

模式路由

先判断数据源，再进入统一流程。

判断规则（按优先级）：

参数以 "历史分析" 开头 → 历史数据源
其他情况 → 会话数据源（默认）

注意：参数中偶然包含"历史"一词（如"分析历史片段"）不触发历史模式。只有参数以"历史分析"作为显式前缀时才切换。

Phase 1: 数据采集

根据模式路由结果，选择对应的数据采集方式。两种方式的输出相同：一组待分析的原始交互数据。

会话数据源（默认）

回顾当前会话内容，直接进入 Phase 2。

历史数据源

从 agent 历史会话日志中批量采集交互数据。

Step 1.1: 环境发现

核心原则: 不硬编码任何路径。利用 agent 的自认知能力自适应定位资源。

识别身份: 确认当前 agent 工具名称（Claude Code / OpenCode / 其他）和数据目录命名惯例（~/.<tool-name>/ 或 ~/.local/share/<tool-name>/）
定位配置文件: 从 cwd 向上搜索，收集所有 CLAUDE.md、AGENTS.md、.claude/CLAUDE.md、.claude/AGENTS.md，记录路径和内容摘要
定位会话历史（按优先级尝试）:
- 已知的 agent 数据目录（~/.<agent-name>/、XDG ~/.local/share/<agent-name>/）
- 搜索常见存储格式（*.jsonl、*.db/*.sqlite、*.json）
- 项目关联筛选（路径/目录名包含当前项目名，或会话内容引用当前项目路径）

向用户报告发现结果（配置文件 + 相关会话数量），确认后继续。

Step 1.2: 读取约束

最多读取最近 20 个会话（避免过量 token 消耗）
优先读取 user 类型消息（用户消息包含偏好信号，agent 回复通常是执行结果）
有 summary/title 字段时，先用摘要快速筛选，跳过明显无关的会话

Phase 2: 信号提取

对采集到的数据，使用以下维度提取有价值的信号。

核心维度（所有模式通用）

维度	关注点
进展顺利	成功的方法、有效的解决方案、好的决策
进展不顺	失败的尝试、错误的方向、浪费时间的地方
明确纠正	用户纠正的地方、拒绝的建议、表达不满的地方。检测纠正短语——中文："不要"/"别"/"不是…是…"/"我说的是"/"请用"；英文："don't"/"stop"/"I said"/"I meant"/"please use"
推断偏好	沟通风格、工具偏好、代码风格、工作流习惯

跨会话维度（仅历史数据源补充）

历史数据源拥有多会话视角，额外检测以下模式：

信号类型	检测方法
重复纠正	对"明确纠正"结果按主题聚类。同一主题跨 ≥2 个会话被纠正 → 信号升级为高优先级
隐含偏好	用户在 ≥3 个会话中对同类选择做出相同决定（工具选择、文件命名、代码风格、沟通语言、响应长度等），但配置中无对应规则
偏好冲突	先提取现有配置中的规则列表。有规则但仍被纠正 → 规则表述不清或已过时，需更新
过时规则	提取配置文件中所有具体行为规则（排除身份性/通用性规则）。最近 10+ 个会话中从未触发且不属于低频场景 → 标记为可能过时
负面情绪	搜索情绪信号词：连续感叹号(≥2)、全大写词(≥3字母)、"又"/"again"/"为什么总是"/"怎么又"。仅标记相关会话片段供人工审查，不直接生成建议——情绪信号需人工判断根因

信号输出格式

对每个提取的信号，记录：

内容: 学习项的具体内容
来源: 来自哪个会话/位置、具体的用户消息片段
频次: 出现次数（频次越高，信号越强）
动作类型: 新增 / 更新 / 标记过时 / 待确认
对应的现有配置规则（如有）

Phase 3: 四层分类

语义定义

层级	核心问题	特性
Layer 1: 用户配置	"每个会话都需要知道什么？"	跨项目、身份性、自动加载
Layer 2: 项目根配置	"这个项目整体需要知道什么？"	项目级、版本控制
Layer 3: 子模块配置	"这个子模块需要知道什么？"	子模块特定、就近原则
Layer 4: 情境记忆	"特定情境下需要召回什么？"	情境性、按需查询

硬规则：单条知识唯一归属

每条学习项选择一个且仅一个存储层。
禁止跨层重复（包括改写后的同义重复）。
写入前，执行跨层去重检查：在所有已探测到的存储位置检索关键词。
发现重复或冲突时，使用 AskUserQuestion 让用户决定（移动 / 覆盖 / 忽略）；默认不自动覆盖。

决策树

对于每个学习项，依次问：
│
├─ Q1: 是否是每个新会话、跨所有项目都需要的信息？
│   ├─ 是 → Layer 1 用户配置
│   └─ 否 → 继续 Q2
│
├─ Q2: 是否与当前项目整体相关？
│   ├─ 是 → Layer 2 项目根配置
│   └─ 否 → 继续 Q3
│
├─ Q3: 是否与项目中某个特定子模块/子目录相关？
│   ├─ 是 → Layer 3 子模块配置（写入最近的子目录配置文件）
│   └─ 否 → 继续 Q4
│
└─ Q4: 是否是特定情境才需要的经验/知识/解决方案？
    └─ 是 → Layer 4 情境记忆

关键区分：

用户配置: "What I always need to know"（身份/常驻规则）
项目根配置: "What this project needs to know"（项目约定）
子模块配置: "What this submodule needs to know"（子模块约定，就近放置）
情境记忆: "What I learned for specific situations"（情境经验）

分类示例

学习内容	层级	理由
"用户偏好 bun 而非 npm"	L1 用户	跨项目的工具选择
"用户偏好简洁响应"	L1 用户	跨项目的风格偏好
"用户偏好中文交流"	L1 用户	跨项目的语言设置
"这个项目有 21 个独立插件"	L2 项目根	项目整体结构
"插件 plugin.json 不要用 $schema 字段"	L2 项目根	项目通用规范
"oc-tweaks 发布必须走 CI，禁止 npm publish"	L3 子模块	oc-tweaks 子模块特定
"openspec proposal 必须包含 Why 和 What Changes"	L3 子模块	openspec 子模块特定
"GitHub Code Search 按相关性排序"	L4 情境记忆	特定技术的经验教训
"并行 API 调用用 ThreadPoolExecutor"	L4 情境记忆	特定场景的解决方案

Phase 4: 存储层探测

在持久化前，先探测当前环境可用的存储后端。不假设任何特定插件或 MCP 存在。

Layer 1-3 — 配置文件（CLAUDE.md / AGENTS.md）

L1/L2/L3 本质相同：都是扫描 CLAUDE.md 和 AGENTS.md，只是扫描层级不同。不硬编码具体路径——不同 agent 工具的用户级目录各异，由 agent 根据自身环境自适应探测。

层级	扫描范围
L1 用户配置	用户级 agent 配置目录（如 `~/.<agent-name>/`）下的 `CLAUDE.md`、`AGENTS.md`
L2 项目根配置	项目根目录及其 `.claude/` 子目录下的 `CLAUDE.md`、`AGENTS.md`
L3 子模块配置	项目子目录中已存在的 `CLAUDE.md`、`AGENTS.md`（排除根目录、node_modules 等）

统一规则：

所有检测到的文件均参与去重检查
写入时选择语义最合适的一个
不存在则创建并添加适当头部
L3 无子模块配置文件时，将 Q3 内容归入 L2

Layer 4 — 情境记忆

按优先级探测：

记忆相关的工具: 当前环境有可调用的记忆存储工具 → 用
已存在的 memory 目录: 项目级或全局 memory 目录（含 *.md 文件）→ 用 Read/Edit/Write
兜底: 以上都不可用 → 在项目内创建 .memory/ 目录，以 markdown 文件存储

原则: 探测到什么用什么。不要求用户安装任何额外依赖。

Phase 5: 用户确认与持久化

Step 5.1: 展示分类

## 学习摘要

### L1 用户配置（写入 {探测到的文件名}）

- [学习项 1]

### L2 项目根配置（写入 {探测到的文件名}）

- [学习项 1]

### L3 子模块配置（写入 {探测到的文件名}）

- [子模块知识 1]

### L4 情境记忆（写入 {探测到的后端描述}）

- [经验 1]

### 标记过时（如有）

- [规则 1] — 原因：最近 N 个会话中从未触发

### 待确认（如有）

- [发现 1] — 需要用户判断：[具体问题]

Step 5.2: 跨层去重（MANDATORY）

对每条学习项，在所有已探测到的存储位置检索关键词，确认是否已存在同义内容。
若发现重复或冲突，向用户展示并用 AskUserQuestion 提供处理选项。
默认不自动覆盖。

Step 5.3: 用户确认

使用 AskUserQuestion 让用户逐条审核：

multiSelect: true
每个学习项作为一个选项（label 含层级和动作类型，description 含内容摘要和来源）

用户可选择全部、部分或跳过。

Step 5.4: 执行持久化

确认后：

阅读目标文件完整内容，理解现有结构
找到语义合适的位置插入/修改：已有相关 section → 合并进去；新类别 → 在相邻 section 附近创建。禁止追加到文件末尾
对于"标记过时"类，不自动删除——仅添加注释标记或询问用户是否删除
子模块特定的知识不要写入根配置（避免上层膨胀）；跨模块的通用知识不要写入子模块配置（避免重复）
Layer 4 策略因后端而异：工具后端用其 API；文件系统后端按主题分类（如 patterns.md），保持简洁，用 bullet points
使用 Edit 工具执行修改
报告保存了什么、保存到哪里

Step 5.5: 记忆整理（仅当使用工具后端时）

仅在使用了支持图谱/实体的记忆工具时执行。文件系统后端不需要。

查看当前数据，识别重复/冲突/孤立内容
合并重复、连接孤立项（不可丢失有价值信息）
向用户报告整理了什么

数据已干净则说明"已检查，无需整理"。

错误处理

场景	处理方式
配置文件不存在	创建并添加适当头部
子模块无配置文件	归入 Layer 2
情境记忆后端不可用	降级到下一优先级后端
所有后端都不可用	使用兜底方案
用户拒绝所有项目	确认并不持久化
找不到会话历史（历史数据源）	报告搜索路径和结果，请用户指定位置
会话格式无法解析（历史数据源）	读取少量样本推断结构；失败则跳过，继续处理其他会话源，最终报告跳过清单及原因
会话数据过大（历史数据源）	严格遵守 20 会话上限，优先最近的
无有意义的模式	如实报告"未发现明显的改进信号"，不生造建议

auto-extract