# Session Knowledge Capture

> Use when 沉淀会话知识/保存发现/记录记忆技能/讨论知识是否值得落盘。会话知识收割：分析会话提取有价值信息，QUIET 分类落盘到记忆或技能，一次调用完成采集→分类→去重→保存→保真度审计→汇报。

- Skill: `yyyyyhhhhh0639/session-knowledge-capture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yyyyyhhhhh0639/session-knowledge-capture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yyyyyhhhhh0639/session-knowledge-capture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: yyyyyhhhhh0639 (https://skillmd.com/u/yyyyyhhhhh0639)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yyyyyhhhhh0639/session-knowledge-capture

---


# 会话知识收割 (Session Knowledge Capture)

## Overview

本技能是 Hermes 自改进循环的上游：**分析对话 → 提取持久价值 → 分类落盘**。它把一次会话中的用户偏好、环境事实、纠正教训、可复用工作流，分别写入记忆（小且常驻）或技能（长且按需加载），并输出保真度审计报告。

调用一次即完成全流程，无需多次追问。默认**自动落盘**，但每次必出收割报告；`--dry-run` 模式只出提案不落盘。

**与相邻技能的分工：**
| 技能 | 职责 |
|------|------|
| 本技能 | 采集 + 分类 + 落盘（上游） |
| `hermes-agent-skill-authoring` | SKILL.md 作者规范/校验（写技能时引用） |
| `memory-storage-management` | 记忆容量/溢出治理（写记忆时引用） |
| `session-housekeeping` | 会话清理/取证（删除归档，不是保存） |

## When to Use

- 用户说"把这次学到的东西记下来 / 保存发现 / 收割 / 沉淀到记忆或技能"
- 完成复杂任务（5+ 工具调用）后，用户要求固化经验
- 会话中出现新的工作流、陷阱、纠正，值得固化为技能
- 定期知识整理（用户触发或 cron 触发）

**Don't use for:**
- 会话清理/删除 → `session-housekeeping`
- 记忆容量治理/压缩 → `memory-storage-management`
- 问"怎么写技能" → `hermes-agent-skill-authoring`
- 单条记忆的临时读写 → 直接 `memory()` 工具

## Invocation Modes

| 调用 | 行为 |
|------|------|
| `/session-knowledge-capture` | **自动模式**（默认）：分析→提取→落盘→汇报 |
| `/session-knowledge-capture --dry-run` | **审查模式**：只出候选清单+提案，不落盘 |
| `/session-knowledge-capture --window N` | 只分析最近 N 轮对话 |
| `/session-knowledge-capture --session <id>` | 分析指定历史会话（用 `session_search` 拉取） |
| `/session-knowledge-capture --all` | 强制全量分析整个会话（必要时 session_search 补历史） |

模式选择：默认自动模式；用户说"先看看 / 提案 / 别动" → dry-run；用户指定范围 → window/session。

---

## 六步管线

### ① 范围确定

**分层决策（从上到下命中即停）：**

1. **用户显式指定** → 遵命（`--window N` / `--session <id>` / `--all`）
2. **会话较短（≤20 轮）** → 全量分析（成本低、不遗漏，无需聪明）
3. **用户意图含"整个会话/今天/全部"** → 全量（必要时用 `session_search` 补历史）
4. **默认：最近一次完整任务**
   - **任务起点**（向前扫描到任务边界）：用户提出新目标（"帮我…"/"接下来…"）/ 主题切换 / 新工具调用序列开始
   - **任务终点**：最后一条用户消息

**物理约束：** 长会话可能超出上下文窗口，全量分析需 `session_search`（FTS5）拉取历史——成本高，故默认不选全量。

**完成标准：** 明确分析窗口，能说出覆盖了哪些对话内容、命中了哪条决策规则。

### ② 候选提取

扫描对话，提取以下五类候选：

| 类别 | 例子 | 落盘目标 |
|------|------|---------|
| 用户偏好 / 沟通风格 | "我喜欢表格 + ASCII 图" | `USER.md` (target="user") |
| 环境事实 / 系统状态 | "GPU 是 RTX 2060，CUDA 12.9" | `MEMORY.md` (target="memory") |
| 纠正 / 教训 | "别用系统 pip，Hermes venv 没有 pip" | `MEMORY.md` |
| 可复用工作流 | "MTEB 查询要遍历全部分片" | 新 `SKILL.md` |
| 现有技能改进 | "housekeeping 术语要匹配 UI" | patch 现有 `SKILL.md` |

**跳过（不进候选）：**
- 琐碎/明显信息（"用户问了 Python"）
- 可再发现**知识**（能 web 搜索/文档查到的）——但**环境型可再发现**（本地命令可查的环境状态）须先过"记忆价值判据"（触发认知 × 提及频率 × 时机敏感度 − 过期风险，见 `memory-storage-management`）：触发认知缺失的环境事实（junction 映射、pwsh 存在、GPU 型号）应进候选——"可推断" ≠ "会被推断"，Agent 不知道要查就永远不会查（2026-08-03 固化，来源 `20260803_105311_eebf93`）
- 原始数据转储（大段代码/日志/表格）
- 会话一次性临时信息（临时路径、一次性调试上下文）
- 已在 context 文件中的内容（SOUL.md / AGENTS.md 已覆盖）

#### 教训条目的落盘规范（防"记住了却没用上"）

记忆里"教训类"条目如果只记录机制、不记录触发信号，防错效果会大打折扣。案例：MSYS 路径坑——机制描述准确，但绑定"环境变量"场景，导致 CLI 参数变体场景未触发应用，重复犯错。**教训条目必须包含四要素：**

| 要素 | 作用 | 例子 |
|------|------|------|
| 触发信号 | 什么场景/特征会命中 | "native Python 程序收到 `/f/` 路径" |
| 判别维度 | 如何区分易错/不易错 | "MSYS 工具没事 vs native 程序会挂" |
| 反例教训 | 什么情况下容易惯性犯错 | "前面 mkdir 成功 ≠ hermes 命令安全" |
| 解决方案 | 怎么做才能避免/修复 | "给 native 程序传路径一律 `F:/AI/...`" |

落盘前自检：
1. **变体场景测试**：这条教训如果只写了机制，下个会话遇到变体场景（环境变量→CLI 参数）会不会再次犯错？会 → 补上要素再落盘
2. **抽象层级**：这是现象级（具体案例）还是方法论级（通用规则）？**方法论 > 现象**——能否抽象一层覆盖更多场景（如"显示层转义×2"→"转义层数压到 1 层"）？优先记录可复用的方法

**完成标准：** 候选清单已生成，每条标注类别与理由。

### ③ QUIET 分类

五维判定（对齐 `hermes-agent-internals`）：

| 规则 | 问题 | 归属 |
|------|------|------|
| **Q**uintessential 本质性 | 去掉这句话，Agent 还是同一个吗？ | SOUL.md（只报告） |
| **U**ser-directed 用户导向 | 是用户偏好还是 Agent 伦理？ | USER.md / SOUL.md |
| **I**mmutable vs Mutable | 跨项目/用户会变吗？ | 变→USER/MEMORY/SKILL；不变→SOUL |
| **E**nvironment-aware | 依赖当前环境/项目吗？ | AGENTS.md / SKILL.md |
| **T**ool-gated | 与具体工具/配置有关？ | config.yaml（只报告） |

决策树：

```
用户偏好/沟通风格？      → USER.md
环境/系统/项目事实？      → MEMORY.md
工作流步骤/陷阱/最佳实践？ → 新 SKILL.md 或 patch 现有
项目开发规则？            → AGENTS.md（只报告）
身份本质？                → SOUL.md（只报告）
运行时配置？              → config.yaml（只报告）
```

**知识类型二分（落盘位置补充）**：流程类（可命令化：步骤/命令/checklist）→ SKILL.md 正文；**判别类**（不等式/锚点，如"信息需求 ≠ 执行授权"）→ references/ 或记忆锚点条目——判别类价值在"决策时刻的分类边界"，可靠性来自反复实例化（须带实例落盘），不能用"能否命令化"否定其价值（2026-08-05 实证，见 rule-enforcement/references/l1-failure-patterns.md）。

**重要边界：** 本技能自动落盘范围**仅限** `USER.md` / `MEMORY.md` / 用户 skill 目录下的 `SKILL.md`。SOUL.md / AGENTS.md / config.yaml 的内容**只报告不落盘**（高影响，需用户明确确认）。

**完成标准：** 每条候选都有明确的归属目标或"只报告"标记。

### ④ 去重（内容级）

- **技能（内容级，先于名称比对）：** 落盘前先对技能库做**内容级 grep**——名称/描述比对会漏掉"知识在内容里但描述不含关键词"的存量技能（2026-08-05 stash 教训：hermes-desktop-internals 内容含完整 stash 机制但描述无 stash 关键词，导致知识被重复落盘）：

  ```bash
  grep -ril "<核心关键词1>\|<核心关键词2>" "$HERMES_HOME/skills" --include="SKILL.md"
  ```

  命中 → `skill_view` 读内容确认是否已覆盖；已覆盖 → patch 现有技能（升级/补充），不新建。`skills_list()` 名称比对只是补充确认，**不是**查重手段。规范出处：`hermes-agent-skill-authoring` §258"查重（内容级）——只做列表比对就新建 = L1 应用失败"。
- **记忆：** 检查系统提示中的记忆快照（冻结）+ `memory()` 工具响应中的 live 状态。精确重复条目 `memory()` 会自动拒绝（返回 "no duplicate added"）。

**完成标准：** 每条候选都确认了 新建 / 更新 / 跳过 三态之一。

### ⑤ 落盘

#### 记忆写入（走 `memory()` 限额）

```python
memory(target="memory", operations=[
    {"action": "add", "content": "..."},
    {"action": "replace", "old_text": "...", "content": "..."},
    {"action": "remove", "old_text": "..."},
])
```

- `operations` 数组**原子提交**：先 remove/replace 再 add，中间超限没关系，只查净结果
- 溢出 → 按 `memory-storage-management` 决策树**原地压缩重试**（85% 阈值 / 连续 3 次规则），不放弃
- 单条内容信息密集、可执行；宁合并多条为一个综合条目（如 "GPU+CUDA+PyTorch" 一条）
- 限额：USER.md 1,375 字符 / MEMORY.md 2,200 字符

#### 技能写入（`skill_manage`）

| action | 用途 |
|--------|------|
| `create` | 新技能（name, content 全量 SKILL.md, category） |
| `patch` | 定向小改（name, old_string, new_string） |
| `edit` | 结构性重写（name, content 全量替换） |
| `write_file` | 添加 references/ 等支持文件 |

#### 写前快照（修改现有技能前必做）

`skill_manage` 的正常写入**没有磁盘级备份**（只有安全扫描失败时才用内存中的 `original_content` 回滚；成功写入即覆盖旧内容）。因此：

- **修改现有技能**（`patch` / `edit`）前，必须先快照：

```bash
cp <skill目录>/SKILL.md <skill目录>/SKILL.md.bak.<epoch秒>
```

- 快照命名对齐 `memory_tool.py` 的 drift backup 惯例：`SKILL.md.bak.<时间戳>`
- 落盘完成后在收割报告中记录备份路径
- `edit` 全量重写风险最高——**能 patch 就不 edit**

新技能创建规范（对齐 `hermes-agent-skill-authoring`）：
- frontmatter 硬性要求：`name` ≤64 chars 小写连字符；`description` ≤1024 chars；正文非空
- peer 体量 8-14K chars 为目标；>20K 拆 `references/`
- 每步带**完成标准**；含 When to Use / Pitfalls / Verification
- 不要造已有技能 —— 先查重（步骤④）

#### 溯源记录（必须）

- 新技能 `metadata.hermes` 下加：

```yaml
metadata:
  hermes:
    provenance:
      created_at: "2026-07-30"
      source_session: "<会话ID或标题>"
      source_context: "<关键决策上下文，含发现性矛盾，不只结论>"
```

- 理由：仅记录结论不保留叙事背景 → 判断依据丢失，后续审计无法还原
- patch 现有技能时，同步更新其溯源注释（如适用）

**完成标准：** 所有待落盘条目已成功写入，或明确报告失败原因。

### ⑥ 保真度审计 + 汇报

提取内容三分类：

| 档位 | 定义 | 处理 |
|------|------|------|
| 高保真 | 原文即价值，无需改写 | 原样或最小改写落盘 |
| 改进版 | 需合并/压缩/重构 | 改写后落盘，报告说明改动 |
| 丢弃 | 琐碎/可再发现/一次性 | 不落盘，报告说明理由 |

**汇报模板（每次调用必出，dry-run 也要出）：**

```
## 收割报告
分析范围：...
候选 N 条 → 落盘 M 条 → 跳过 K 条

| # | 内容摘要 | 落盘目标 | 动作 | 状态 |
|---|---------|---------|------|------|
| 1 | ... | MEMORY.md | add | ✅ 新增 120/2200 字符 |
| 2 | ... | 新技能 xxx | create | ✅ 已创建 |

跳过及理由：
- ...（保真度档位 + 理由）

⚠️ 注意：memory() 落盘立即写入磁盘，但系统提示中的记忆快照要到下个会话才更新。
```

### 结论分层标注（2026-08-04 固化）

调查/结论类输出按证据层级组织，禁止推断混入事实：

| 层级 | 定义 | 输出要求 |
|------|------|---------|
| 事实 | 可指认证据支持 | 注明证据来源（快照/日志/实测） |
| 推断 | 有依据但未确证 | 标注依据 + 为什么不是事实 |
| 未确证 | 存在证据缺口 | 写明缺什么才能确证 |

原理：格式倒逼语义——分类动作触发自检，不依赖"想起"抽象规则
（USER.md R3 的 evidence-based 是判断规则，三层标注是格式规则；
  2026-08-04 lens 实证：自由叙述时推断被叙事填充违规，分层输出合规）

**主动前置**（2026-08-04）：调查/结论输出时**默认**先分层，不等被要求——被动响应（被质疑/被指出后才分层）是应用失败的表现，与 MSYS 路径教训同源。

**技能调用链主动前置**（2026-08-04 下午实证）：本技能流程引用的子技能/步骤——④ 查重须 `skill_view` **内容级**对比（不止 `skills_list` 名称比对）、写记忆前须加载 `memory-storage-management` 跑价值判据四问 + 85% 阈值检查——在**进入对应步骤时默认加载执行**，不等被质疑。被动补执行（"没有查重阶段吗"/"没有调用价值判断技能吗"）是同一失败模式（与"结论分层主动前置"同源），2026-08-04 收割会话两次实证：列表查重后漏内容级对比即新建技能、写入记忆前漏价值判据。

**证据层级原则**（2026-08-04 lens 实证）：文件快照差异只能证明"内容变了"，不能证明"决策意图"——除非找到决策记录（会话/日志/审批链）。推断意图前先问：有决策记录吗？没有 → 标"未确证"。

---

## Common Pitfalls

1. **收割琐碎内容** — 严格用"跳过标准"过滤；拿不准时问用户，不猜
2. **记忆溢出后放弃** — 必须原地压缩重试（`memory-storage-management` 决策树），不允许静默丢弃
3. **新建重复技能** — 先 `skills_list()` 查重；高度重叠走 patch，不另起炉灶
4. **覆盖用户手改的现有技能** — patch 前先 `skill_view` 对比；结构性大改先 dry-run 提案
5. **丢失叙事背景** — 溯源记录必须含决策上下文（含发现性矛盾），不只结论
6. **越界自动改 SOUL.md / AGENTS.md / config.yaml** — 禁止，只报告
7. **报告缺失** — 无论 dry-run 还是自动模式，每次调用必出收割报告
8. **edit 覆盖无备份** — 修改现有技能前必须 `.bak` 快照；`edit` 全量重写风险最高，能 patch 不 edit

## Verification Checklist

- [ ] 报告包含分析范围、候选/落盘/跳过计数
- [ ] 每条落盘内容标明了目标文件与动作
- [ ] 新技能 frontmatter 通过校验（name / description / 非空正文）
- [ ] 记忆写入未超限；若溢出已压缩重试成功
- [ ] 溯源记录已写入（created_at / source_session / 决策上下文）
- [ ] 修改现有技能前已生成 `.bak` 快照（路径已记录）
- [ ] 未触碰 SOUL.md / AGENTS.md / config.yaml
- [ ] 跳过项均有理由（保真度档位）