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

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

触发方式

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

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

完整触发示例见 [references/trigger-examples.md](references/trigger-examples.md)。

架构

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

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

输出精炼模型

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

归档详情见 [references/archive-model.md](references/archive-model.md)。

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

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

平台检测表

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

路径变量映射表

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

存储层级 — 4层金字塔

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

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

边界场景与降级

场景处置（自动修复型）

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

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

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：会话精炼 — 发生了什么

输出格式

📋 {项目名} — {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：进度总结 — 做到哪了

输出格式

✅ 本轮完成({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 健康检查）

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

3.2 知识沉淀

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

3.3 记忆健康度

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

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

失败6类

5维分类 ↔ 6类失败 映射

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类失败（屏幕显示）。温区条目同时记录两个分类字段。

输出

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

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

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

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

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

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

5.1 自动采集触发条件

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

5.2 成功经验分类标签

5.3 输出格式

⚡ 成功经验({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 写入层级决策树

经验记录
  │
  ├── 涉及具体项目路径/文件/配置/架构？
  │     └── 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 分层写入目标文件

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

6.3 待确认队列

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

❓ 待确认({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 输出格式

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

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

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

Headroom 集成

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

检测链路

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) → 检查环境变量

双轨存档（总结 压缩）

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 不可用时退化为纯明文模式。

子命令

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

定位：将温区高复发错误升级写入 L0 热区 P0 表，完成闭环关键步骤。

触发条件：模块4 判定某条温区错误满足「14d内复发≥2次」且「热区<5条有空位」。

操作步骤

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}"

输出格式

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

错误处理

文件结构

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](references/installation.md)。

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

反馈

🐛 [GitHub Issues](https://github.com/gtbwpkwjnb-alt/summarize-skill/issues/new)

License

MIT — see [LICENSE](LICENSE) file.