Session Knowledge Capture

会话知识收割 (Session Knowledge Capture)

Overview

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

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

与相邻技能的分工：

When to Use

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

Don't use for:

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

Invocation Modes

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

六步管线

① 范围确定

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

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

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

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

② 候选提取

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

跳过（不进候选）：

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

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

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

落盘前自检：

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

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

③ QUIET 分类

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

决策树：

用户偏好/沟通风格？      → 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 关键词，导致知识被重复落盘）：

  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() 限额）

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）

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

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

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

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 下加：

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
• 跳过项均有理由（保真度档位）