Summarize

Compresses long AI coding sessions into glanceable summaries with progress tracking, error harvesting, and layered memory writing. Supports 5-dimension error classification, dual-track self-evolution (success + error), 4-tier layered writing (project/global/skill/pending), and 5-level graceful degradation. Triggered only by standalone word '总结' or 'summarize' — not in sentences, no auto-reminder. 将长AI编程会话精炼为一眼可读的摘要，含进度追踪、错误收割与分层记忆写入。支持5维错误分类、双轨自进化（成功+错误）、4层分级写入（项目/全局/技能/待确认）、5级降级链。仅独立词'总结'或'summarize'触发——句中不触发、无自动提醒。

session-summarize v6.6.3 — 会话精炼·进度追踪·错误收割·双轨自进化·分层写入·跨平台适配

定位：AI 编程助手的错误免疫系统 + 会话压缩引擎。自动收割错误 → 5维分类 → 分层记忆写入 → 生成预防规则 → 追踪遵守 → 收敛预警。同时精炼长对话为结构化进度报告。

---

触发方式

唯一触发词：总结 或 summarize，必须作为独立词单独发送。

✅ 会触发	❌ 不会触发
总结（单独发送）	"总结一下今天的工作"（在句中）
summarize（单独发送）	"帮我总结一下进度"（在句中）
总结 统计（独立词+参数）	会话达到任意阈值（无自动提醒）

⚠️ 无自动提醒、无定时触发、无其它激活路径。仅独立词触发。

完整触发示例见 references/trigger-examples.md。

---

架构

text

触发（独立词 总结 / summarize）
    │
    ├─ 模块1: 会话精炼 (Session Condense)         ← 核心  主/次任务分层+进度条
    ├─ 模块2: 进度总结 (Task Progress)            ← 核心  完成/待办/下一步
    ├─ 模块3: 建议总结 (Suggestions)              ← 核心  链路优化+知识沉淀+记忆健康度
    ├─ 模块4: 错误总结 (Error Harvest)            ← 核心  ≤5错误
    ├─ 模块5: 成功经验 (Success Harvest)          ← 核心  工具效用对比+最佳路径
    └─ 模块6: 分层写入 (Layered Write)            ← 核心  决策树+待确认队列

四级闭环:
  回测 → 规则沉淀 → 下次验证 → 更新干净天数
  分级 → 错误检测 → 全局/项目分流
  自进化 → 错误模式 → 规则建议 → 全局/项目分流
  技能分析 → 调用追踪 → token 估算 → 效果评估

---

输出精炼模型

每个模块有硬上限。超出部分自动折叠为 📦 详见归档，完整内容写入归档文件。

模块	上限	超出处理
模块1 文件清单	8个	…等{N}个文件 📦
模块1 关键决策	5条	…等{N}条决策 📦
模块4 错误列表	5条	…等{N}条错误 📦
整体输出	≤25行	超限优先折叠模块4→模块3→模块5

归档详情见 references/archive-model.md。

---

平台适配 — 自动检测 Agent 平台

首次运行时自动检测当前 Agent 平台，适配 L0 全局规则路径、项目记忆文件路径、技能目录路径。

平台检测表

检测顺序：依次检查以下路径是否存在，首次命中即确定平台。

优先级	平台	L0 全局规则路径	项目记忆文件	技能目录	检测方式
1	ZCode	~/.agents/AGENTS.md	./MEMORY.md	~/.agents/skills/	默认
2	CodeBuddy	~/.codebuddy/AGENTS.md	./CODEBUDDY.md	~/.codebuddy/skills/	检查 ~/.codebuddy/
3	Claude Code	~/.claude/CLAUDE.md	./CLAUDE.md	~/.claude/skills/	检查 ~/.claude/
4	Codex	~/.codex/AGENTS.md	./MEMORY.md	~/.codex/skills/	检查 ~/.codex/
5	Reasonix	~/.reasonix/AGENTS.md	./REASONIX.md	~/.reasonix/skills/	检查 ~/.reasonix/ 或 reasonix.toml

路径变量映射表

变量	含义	模块6写入时使用
$L0_RULES	平台对应的 L0 全局规则路径	全局级规则写入
$L0_MEM_DIR	L0 规则同目录下的 memories/ 子目录	全局级记忆写入
$PROJ_MEMORY	平台对应的项目记忆文件名	项目摘要写入
$SKILL_BASE	平台对应的技能目录	技能级写入

降级安全：L0 规则文件不可读时不影响核心功能。写入目标目录不存在时自动创建。

---

存储层级 — 4层金字塔

基址：$HARVEST_BASE=~/.agents/skills/summarize/harvests/（固定路径，文件不存在时自动创建）。

层级	位置	定容	加载方式
🔥热区	$L0_RULES P0表	≤5条	hook 每次 session 自动注入
🔶温区	$HARVEST_BASE/{project}/errors.md	≤30条	按需检索
🔵冷区	$HARVEST_BASE/error-ledger.md	≤100条	总结时 + 主动检索
⬜归档	$HARVEST_BASE/archive/	无上限	显式恢复，永不自动加载

常驻负担：仅热区 ~2KB / ~500 token（hook 注入），温冷区按需加载。

---

边界场景与降级

场景处置（自动修复型）

场景	行为	输出
基址目录缺失	自动创建 harvests/	ℹ️ 已创建 harvests 目录
归档文件损坏	跳过该文件，重建空文件	⚠️ 归档损坏，已重建
旧版数据格式（v5）	自动迁移到 v6 结构	↻ 数据格式已迁移 v5→v6
会话 ID 冲突	保留新归档，旧归档标 [superseded]	↻ 会话已覆盖旧归档
温区/冷区文件编码错误	重建空文件，原文件备份为 .bak	⚠️ 编码异常，已重建（原文件→.bak）

降级链（5级递进 · 双轨独立降级）

核心原则：降级后每次仍尝试写入（检测恢复条件）。逐级恢复（非跳回L0）。模块5(成功轨) 与模块4(错误轨) 独立降级。

text

L0 正常（全模块：1+2+3+4+5+6）
  │  触发条件: 无异常
  ▼
L1 模块4降级（仅内存统计）+ 模块5+6正常
  │  触发条件: 温区/冷区/索引 写入失败(1次)
  ▼
L2 模块3.3+4 跳过 + 模块5+6正常
  │  触发条件: 温区/冷区写入连续2次失败
  ▼
L3 仅进度+事实（模块1+2精简输出，5仅内存，6跳过）
  │  触发条件: harvests/ 整体不可访问 OR L0 规则不可读
  ▼
L4 单行摘要（极限降级）
  │  触发条件: harvests/ 整体不可访问 + L0 规则不可读 OR 连续3次任意写入失败

恢复规则（逐级恢复）：

• L4→L3: 连续2次温区写入成功
• L3→L2: 连续2次冷区写入成功 + L0 规则恢复可读
• L2→L1: 连续2次温区+冷区同时写入成功
• L1→L0: 连续2次温区+冷区+索引全部写入成功

降级状态持久化到 $HARVEST_BASE/_degradation.json。

---

模块 1：会话精炼 — 发生了什么

输出格式

text

📋 {项目名} — {1句话核心概括}

🎯 主任务
  {主任务描述}
  进度 ████████░░ 80%
  > 完成: {已完成部分简述}
  > 待办: {待办部分简述}
  > 阻塞: {如有阻塞项，无则省略此行}

📌 次任务
  {次任务1描述}  ██████░░░░ 60%
  > {简述}
  {次任务2描述}  ████░░░░░░ 40%
  > {简述}
──────────────────────────────
📁 涉及文件({N})
  ✏️ 修改: {file1}, {file2}, ...
  ➕ 新增: {file3}
  🗑️ 删除: {file4}
──────────────────────────────
🔑 关键决策({N})
  - {决策1}：{1句理由}
  - {决策2}：{1句理由}
  > 超{N}条折叠为 📦 详见归档

规则

• 主任务：当前会话最核心的1个任务（从用户指令推断）
• 次任务：并行/附带的其他任务，最多列3个
• 进度条：10格 ASCII 进度条（█已完成 ░未完成），基于已完成步骤/总步骤
• 小字：> 小字 引用块注解细节，不占主行计数
• 无次任务时省略 📌 次任务 块
• 无阻塞项时省略 > 阻塞 行
• 文件清单超 8 个时，只显示前 8 个 + …等{N}个文件 📦
• 决策超 5 条时，只显示前 5 条 + …等{N}条决策 📦

---

模块 2：进度总结 — 做到哪了

输出格式

text

✅ 本轮完成({N})
  - {完成项1}
  - {完成项2}
  - {完成项3}

⏳ 待办({N})
  - {待办项1}
  - {待办项2}

💡 下一步
  1. {具体可执行行动}
  2. {具体可执行行动}
  > {可选的小字说明/注意事项}

📊 ~{N}轮 ｜ 压力 🟢{<50%} / 🟡{50-80%} / 🔴{>80%}

规则

• 压力等级：根据待办/完成比例
  • 🟢 绿：待办 < 50%（进展顺利）
  • 🟡 黄：待办 50-80%（需关注）
  • 🔴 红：待办 > 80%（积压严重）
• 下一步：必须给出 1-2 条具体可执行的行动（非泛泛建议）
• 无完成项时 ✅ 本轮完成(0) 可省略
• 无待办时 ⏳ 待办(0) 可省略

---

模块 3：建议总结 — 怎么优化

3.1 链路优化（基于台账模式匹配 + headroom 健康检查）

检测模式	触发条件	优化建议
重复构建失败	连续2+会话构建失败	"建议 go mod tidy 前置"
环境缺失	缺工具/依赖/服务	"创建环境检查脚本"
重复错误尝试	重试≥2次未换方向	"设2次失败后自动换路"
配置遗漏	缺 .env/配置	"创建 .env.example + 校验"
重复失败模式	台账同类≥3次	"提升为项目约定"
无效步骤	做了无用操作	"改前先 Read 确认"
Headroom 静默降级	proxy.log 含 rust_core_missing	"检查 headroom Rust core"
Headroom 0 节省	proxy_savings.json tokens_saved=0	"确认代理是否生效"

text

⚡ 链路优化({N}):
  ├ {模式}: {1句建议}
  └ 依据: {N}次重复 | {示例}

3.2 知识沉淀

text

📌 知识沉淀({N}):
  🏗️ {架构决策} ｜ ⚠️ {坑点}→{方案} ｜ 🔧 {配置} ｜ 📐 {约定}

3.3 记忆健康度

text

📊 记忆健康度:
  🔥 热区规则({N}/5 🟢) ｜ 常駐≈2KB ✅
  🔶 温区({N}/30 🟢) ｜ 🔵 冷区({N}/100 🟢)
  🪖 Headroom: {状态} ({节省} token) ｜ {压缩引擎}
  💡 建议 `总结 压缩` 节省空间

层级	健康标准	🟢	🟡	🔴	超限动作
🔥热区	≤5条/≤2KB	<80%	80-95%	>95%	降级最旧1条到温区
🔶温区	≤30条	<24	24-28	≥29	归档最旧10条到冷区
🔵冷区	≤100条	<80	80-95	≥96	归档 days_clean≥90 到 archive/

---

模块 4：错误总结 — 出了什么问题

失败6类

代码	类型	检测方式
TOOL_ERR	工具报错	API error / denied / timeout
EXEC_FAIL	执行失败	build error / test fail
ENV_MISS	环境缺失	缺命令/依赖/服务
CFG_MISS	配置缺失	缺 .env/配置文件
RETRY	重复尝试	重试≥2次未换方向
LOGIC	逻辑偏差	用户纠正/无用功

5维分类 ↔ 6类失败 映射

text

5维分类（L0规则体系）       →  6类失败（屏幕输出）
─────────────────────────────────────────────────
PROC  流程违规               →  RETRY / LOGIC
ASSU  假设错误               →  CFG_MISS / LOGIC
ENVR  环境问题               →  ENV_MISS / EXEC_FAIL
TOOL  工具误用               →  TOOL_ERR / LOGIC
KNOW  知识盲区               →  CFG_MISS / LOGIC / ENV_MISS

模块3 收割使用 5维分类（写入 L0/温区/冷区），模块4 输出使用 6类失败（屏幕显示）。温区条目同时记录两个分类字段。

输出

text

⚠️ 错误({N}): {高频类型}({N}次)
| {简述} | 类型 | {N}次 | 状态 |
|-------|:----:|:---:|:----:|
| {前5条} | ENV_MISS | 3 | ✅ |

🛡️ 规则: {已采纳}/{总} ✅ ｜ {复发}/{总} ⚠️

💡 即时优化({N}):
  ├ {类型}: {具体修复}
  └ → {预期效果}

📏 规则定容:
  🔥 当前{N}条 ｜ clean最长: {规则}({N}天)
  💡 clean>30天未触发 → 建议降级

---

模块 5：成功经验收割 — 什么做对了

定位：与模块4(错误轨)对称的成功轨。自动采集会话中的成功操作模式、工具效用对比、最佳执行路径。

5.1 自动采集触发条件

触发场景	采集内容	记录类型
工具调用成功且非平凡操作	工具名 + 参数模式 + 耗时 + 结果摘要	tool_success
同一任务使用多种工具并对比	工具A→结果 vs 工具B→结果 + 效率对比	tool_compare
搜索→定位→修改 完整成功链路	完整执行路径 + 跳过的错误分支 + 总耗时	best_path
错误后成功恢复	错误类型 → 修复策略 → 成功结果	recovery_pattern
用户明确表扬/确认/采纳	当前操作模式 + 用户反馈标记	user_approved

非平凡判定（不触发采集）：单次 read_file 无后续修改、单次 list_dir 浏览、单次 search_content 未产生决策、被用户纠正后放弃的操作。

5.2 成功经验分类标签

标签	含义	示例	默认写入层级
🏗️ 架构	项目结构/模式发现	"此项目用 monorepo"	项目级
⚠️ 坑点	已避开的陷阱	"PowerShell 不支持 &&"	全局级
🔧 配置	环境/工具配置经验	"Python 3.12，需用 uv"	项目级
📐 约定	项目代码规范	"错误处理统一用 result pattern"	项目级
⚡ 路径	最佳执行路径	"符号查找优先 codegraph"	全局级
🔬 效用	工具效用对比	"WebFetch vs web_search"	全局级

5.3 输出格式

text

⚡ 成功经验({N}):
  ├ ⚡ 路径: 符号查找→优先 codegraph(0.8s)，降级 grep(3.2s)
  ├ 🔬 效用: WebFetch 长文提取 > web_search，后者适合快速搜索
  └ 🏗️ 架构: 此项目 monorepo，修改需同时更新3个包

📊 工具效用对比(1):
  ├ 任务: 查找 createUser 所有调用点
  │  路径A: grep "createUser" → 47个结果(含 node_modules) → 3.2s
  │  路径B: codegraph callers → 3个结果(全精准) → 0.8s
  │  结论: codegraph 效率高 4x，精度高 15x
  └ → 写入: 全局级 (工具选择策略)

---

模块 6：分类路由与分层写入

定位：将模块4(错误)和模块5(成功)采集的经验，按分类路由写入对应层级文件。

6.1 写入层级决策树

text

经验记录
  │
  ├── 涉及具体项目路径/文件/配置/架构？
  │     └── YES → 项目级 (./.agents/memories/ 或 $PROJ_MEMORY)
  │
  ├── 涉及通用工具选择策略/Agent行为模式/跨项目通用？
  │     └── YES → 全局级 ($L0_MEM_DIR 或 $L0_RULES)
  │
  ├── 涉及具体用户偏好/个人约定？
  │     └── YES → 全局级 ($L0_MEM_DIR/user-preferences.md)
  │
  ├── 涉及特定技能执行优化？
  │     └── YES → 技能级 ($SKILL_BASE/summarize/references/learned/)
  │
  └── 无法确定归属？
        └── → 待确认队列 (_pending.json) → /总结 时询问用户

6.2 分层写入目标文件

路径使用平台变量，各平台自动替换。

层级	路径（变量）	内容	写入触发
L0 全局规则	$L0_RULES	通用行为规则、工具选择策略	效用对比结论、通用最佳路径
L0 全局记忆	$L0_MEM_DIR	用户偏好、全局经验	用户偏好发现、跨项目通用经验
项目级记忆	./.agents/memories/	项目结构、配置、约定	项目特定经验、架构发现
项目摘要	./$PROJ_MEMORY	项目记忆摘要（供 agent 读取）	每次 /总结 时更新
技能级	$SKILL_BASE/summarize/references/learned/	技能执行经验	技能特定优化
待确认	$HARVEST_BASE/_pending.json	无法归类的经验	不确定时暂存

6.3 待确认队列

经验同时满足多个层级归属 OR 与已有规则冲突 OR 涉及用户主观偏好且无历史 → 进入 _pending.json。

text

❓ 待确认({N}):
  [1] "PowerShell 避免 curl，用 Invoke-WebRequest"
      候选: A)全局级 B)项目级 C)跳过
  [2] "Go 版本锁定 1.22" [冲突: go.mod 写 1.21]
      候选: A)以代码为准 B)以经验为准 C)保留两者
  回复 "确认 1A 2A" 完成分类

确认后处理：用户回复 → 写入对应层级，移除。连续3次未确认 → 自动降级写入项目级，标 [auto]。

6.4 输出格式

text

📝 写入({N}):
  ├ → 项目级(2): 🏗️架构: monorepo结构 | 🔧配置: Python 3.12+uv
  ├ → 全局级(1): ⚡路径: codegraph优先策略
  └ → 技能级(0): —

❓ 待确认(1):
  [1] "PowerShell 避免 curl" → 候选: A)全局 B)项目 C)跳过

模块6「待确认」行不计入25行上限（追加在末尾）。

---

Headroom 集成

每次 总结 自动检查 headroom 代理健康与节省统计。

检测链路

text

Read ~/.headroom/logs/proxy.log (末20行)
  → ERROR/WARNING 含 rust_core_missing/python_only_degraded
  → 记入 error-ledger.md (PROC | TOOL:Headroom)

Read ~/.headroom/proxy_savings.json
  → lifetime.tokens_saved / total_input_tokens / compression_savings_usd
  → 记入 _self-stats.md

输出

• 降级 → 🪖 Headroom: 降级 ⚠️ → 高风险预警
• 正常 → 🪖 Headroom: 正常 ({节省} token) ｜ Kompress/基础
• 0 节省 → 🪖 Headroom: 待确认 (0 token) → 检查环境变量

双轨存档（总结 压缩）

text

1. 明文压缩: archive/{date}-errors-compact.md
2. headroom_compress(明文) → hash
3. hash → archive/{date}-errors-compact.md.hr

检索优先级:
  ① headroom MCP → headroom_retrieve(hash) → 解压
  ② 无 headroom   → 读取明文 .md (fallback)

降级安全：headroom 不可用时退化为纯明文模式。

---

子命令

命令	功能	输出
总结 统计	全局统计	📊 运行{N}次 | 采纳率{NN}% | 复发率{NN}%
总结 压缩	压缩归档 + headroom 双轨	📘 {N}→{N} | 🔵 {N}→{N} | 💾 ~{N}KB | 🪖 {hash}
总结 知识库	查看知识库	📚 {N}条 > {最近3条}
总结 台账	查看台账	📊 {N}条 > ✅{N} ⚠️{N}
总结 遗忘	清理记忆	📋 {N}条可清理 > 建议 forget 最久未引用的2条
总结 深度 链	因果链分析	🔗 A→B→C
总结 深度 验证	出站验证	🌐 参考: {URL}
总结 深度 自检	对抗性自检	✅ 通过 / ⚠️ 疑虑
总结 深度 写入	自编辑规则（L0回写）	温区高复发错误升级写入 L0 热区 P0 表

---

深度子命令：总结 深度 写入

定位：将温区高复发错误升级写入 L0 热区 P0 表，完成闭环关键步骤。 触发条件：模块4 判定某条温区错误满足「14d内复发≥2次」且「热区<5条有空位」。

操作步骤

text

Step 1: Read — 加载 L0 规则文件
  → Read $L0_RULES → 定位 P0 热区表
  → 解析当前热区条目数、最旧条目、clean天数

Step 2: 定位 — 计算插入位置
  → 热区<5条 → P0 表末行追加
  → 热区=5条 → 先定容（Step 3）再插入
  → 条目已存在 → 更新次数+状态为 🔄复发，不新增行

Step 3: 定容 — 热区≤5条约束
  → 找最旧1条 → 从 P0 表移除 → 降级写入温区（标 [L0降级]）
  → 输出: "📏 定容: {旧规则} → 温区 | {新规则} → 热区"

Step 4: 插入 — Edit 写入
  → Edit 工具精确替换 P0 表区域
  → 失败 → 重新 Read → 重试1次
  → 仍失败 → 降级写入温区，标 [L0回写失败]

Step 5: 回测 — 验证
  → Read $L0_RULES → 确认 P0 表已更新
  → 输出: "✅ 回测通过: P0表 {N}/5"

Step 6: commit — 版本记录
  → git add + commit
  → Git 不可用 → 跳过，输出 "⚠️ Git 不可用，规则已写入但未提交"

Step 7: 更新温区 — 标记来源
  → 温区对应条目追加 "→ 🔥 已升级热区 {date}"

输出格式

text

🖊️ 深度写入:
  ├ Read: $L0_RULES (P0表 {N}/5)
  ├ 定位: 热区有空位，追加到第{N+1}行
  ├ 定容: 无需（当前{N}条）
  ├ 插入: "P0-{规则简述}" → P0表
  ├ 回测: ✅ P0表 {N+1}/5
  └ commit: ✅ a1b2c3d "升级温区规则到热区 [{规则}]"

错误处理

场景	行为
L0 文件不可读	降级写入温区，标 [L0不可读]
Edit old_str 不匹配	重新 Read → 重试1次 → 仍失败则降级温区
Git 不可用	跳过 commit，输出警告
温区更新失败	不影响热区写入成功的结果

---

文件结构

text

summarize/
├── SKILL.md                    # 技能主文件
├── VERSION                     # 版本号
├── LICENSE                     # MIT
├── README.md                   # 概览与安装
├── sutras.yaml                 # 规则配置
├── scripts/
│   ├── install.ps1             # Windows 安装脚本
│   └── install.sh              # Linux/macOS 安装脚本
├── references/
│   ├── CHANGELOG.md            # 完整变更日志
│   ├── trigger-examples.md     # 触发规则与输出示例
│   ├── installation.md         # 安装方式与平台前置条件
│   ├── skill-analytics.md      # 技能调用统计详细规范
│   ├── archive-model.md        # 归档模型详细说明
│   └── learned/                # 技能级经验（运行时填充）
└── harvests/                   # 运行时数据
    ├── index.md                # 收割索引
    ├── error-ledger.md         # 全局错误账本
    ├── _self-stats.md          # 自反馈统计
    ├── _pending.json           # 待确认队列
    ├── _degradation.json       # 降级状态
    └── {project}/
        ├── errors.md           # 项目错误账本
        └── {session-id}.md     # 会话归档（覆盖更新）

---

安装

一键安装与手动安装详见 references/installation.md。

安装后输入 总结 或 summarize 即可触发。

---

反馈

🐛 GitHub Issues

---

License

MIT — see LICENSE file.