session-digger

你说了什么、做了什么、学到了什么——全在这。只做路由，不做分析。

支持环境：Antigravity (Google)、DSH (DeepSeek)、ZCode (v2 & SQLite)、Claude Code、Grok Build、Kimi Code、Kimix CLI、Codex、Cursor、WorkBuddy、Trae (Global & CN)、Qwen Code、Cline / Roo Code、DIM、Reasonix + 通用对话导入（/import）。数据根默认收归 ~/.session-digger/（向下兼容遗留路径），路径与数据根均通过环境探测，不绑定特定 Agent 宿主目录。

子技能调度协议（0.9.18）

在 保持四层架构与主命令精炼 的前提下，子技能是专精增益层，不是第二套内核。

1. 专精优先：用户意图与某子技能 description 高度匹配时，先加载该子技能，不要只用泛化主命令空转。
   例：「错误根因 / 意图分类」→ deep-analysis；「环境坏了」→ env-doctor / native-diag。
2. 索引先行：分析类子技能前确认索引可用（/index 或 index-builder.py build）；定位会话走 index.db（见 skills/common_paths.py）。
3. combo 收尾：主命令或子技能完成后读 combo_map.json 对应 next，只提示 1–2 个下一步，不输出整张路由表。
4. 不塌层：子技能不私自入库、不替代 echolib；L3 提案（optimize / apply）必须人审。
5. 目标：新主路由 + 调优子技能 优于 新主路由 + 未挂载的老子技能（路径对齐 + combo 可达 + 专精优先）。

Path resolution

SD_ROOT="$(scripts/resolve_root.sh)"   # 相对本 skill 根目录调用

探测优先级与常见安装位写在脚本里。多副本并存时务必 export SESSION_DIGGER_ROOT。禁止硬编码个人仓库路径。

路由前扫一眼：只有「帮我看看」「查一下」没具体内容的 → 问一句「查什么——会话？时间线？经验？」。有「之前」「上次」但没时间/关键词的 → 问一句「大概什么时间？记得什么关键词？」

主命令

做完后读 combo_map.json 提示下一步。不输出路由过程。

/usage 与 /cache-audit — 跨环境 token 可观测与缓存命中体检

• 跨环境汇总各模型账单级 token 与缓存命中率（非产品侧 quota 面板）。取法（family 模式，主/子不双计）与口径：references/usage.md。
• 缓存命中水平深度体检：/cache-audit（或 python3 scripts/cache-audit.py [--env <env>] [--model <pattern>]）。产出环境整体体检（Table A）、模型层级性能（Table B）、排除与异常账本（Table C）及综合健康评分与优化建议。口径规则：references/cache-report-rules.md。

/recall 常用变体

• 最近一次会话摘要 → /recap 或 /recall --recap
• 话题切分 / 主题总览 → /topics、/topic-scan
• 跨环境搜索 → /recall --agent cross
• 压缩后恢复决策点 → /recall --decisions

/reflect 常用变体

• 周/月环比、工具回归 → /trend
• 跨会话技能差距、SKILL.md 提案 → /optimize
• HTML 使用报告 → scripts/reflect-report.py

/analyze 常用变体

• 经验教训 / 踩坑回顾 → /lessons

检索预算与停止条件

读会话历史是最容易失控的动作：一次查询的命中会成片增长，而每一条都要进上下文。默认按下面的额度走。

• 正文与工具输出分两层：默认只匹配人写的正文。工具输出是独立分面（facet=TOOL），--include-tools 才并入，专查用 index-builder.py search <词> --tools-only。实测依据：并入默认检索时，一个只在命令输出里出现过的词会让 top-20 里的 7 行变成工具摘要（占 35% 版面），而换回的独有命中只有 10%。
• 空结果不是结论：一次查询为空只说明「这个范围里没有」。空结果会打印作用域、索引状态、以及同词在更大范围里的命中数——按提示换范围再问一次，然后才下结论。

子命令

以下命令仍可用，经标志、子命令文件或专项 skill 进入（不必从主表记忆）：

查表：references/command-map.md（子命令 / 专项 skill 的完整入口，主表没命中时再读）。

子技能一览（skills/）

完整清单（12 个，含层与入口）见 skills/README.md——单一真源，此处不复述，避免两张表漂移。路由时按子技能 description 匹配（见上方调度协议）。

共享路径：skills/common_paths.py（SESSION_DIGGER_DATA_DIR / index.db）。

Architecture / Speed tier

四层模型（PARSE → INDEX → TREND → DECISION）与速度分级的完整说明见 CLAUDE.md——单一真源。路由只需记住一条：Never collapse layers，各层成本与信任级别不同。

DO NOT

• 从零创建新 skill → skill-search（全生命周期主干：创建/审计/优化/发布）
• 实时监控会话 → Claude Code 原生能力
• 修改/编辑会话 JSONL 文件 → 只读分析，不写原始数据
• 替代 git log → git-mining 是补充视角，不是替代
• /apply 写规则前未经用户审批 → 必须 y/n/e/a/q 逐条确认
• /import 不做微信解密 → 微信数据识别分析走 wechat-digger 子技能（自带只读查询；密钥提取与解密实现不分发，需用户自备已解密库）
• /optimize 自动编辑 SKILL.md → 只草拟提案，必须用户确认后手动应用
• 趋势分析替代单会话分析 → 趋势看方向，单会话看细节，两者互补
• 在命令/文档中硬编码个人机器路径（如某用户家目录下的私有仓库）→ 只用 Path resolution
• /optimize 输出默认不应含绝对路径或用户名 → skill-gap-finder 已脱敏；需要路径时显式 --include-paths

Cache hit rate reporting（强制口径）

面向用户的缓存表 / 环境对比，只报会话均命中率（rate > 0 的会话算术平均）。

• 不要默认输出 Token 加权命中率（除非用户明确要求「按 token 加权」）
• 零缓存 / 无字段 / 未标注模型 / 有效会话 < 3 → 进排除清单，不进主表
• API：echolib.build_cache_hit_tables / mean_cache_hit_rate / cache_rate_eligible
• 全文：references/cache-report-rules.md

Gotchas

Changelog

版本历史（v0.3 → 当前，含旁线条目）在 CHANGELOG.md。此处不再内联：它占 79% 的篇幅， 而本文件每次激活都会整体进上下文。要查「改了什么、为什么改」读那里。