# Session Health

> Session Health: assess the current AI coding tool session — context compaction/condensation ratio, message count, context occupation cost, work nature, recoverability (git/handoff/runtime), and token economics — to judge continue vs new-session. Reads tool session storage read-only. Use when the user mentions context compaction, starting a new session, high context overhead, or long-session continuation (e.g. "go" / "keep going"). NOT for: auditing skill descriptions, full-codebase architecture analysis, or product-doc set audits.

- Skill: `ninjasln-labs/session-health` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ninjasln-labs/session-health`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ninjasln-labs/session-health/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: NinjaSln-labs (https://skillmd.com/u/ninjasln-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ninjasln-labs/session-health

---

# 会话健康度评估（Session Health）
在长会话中评估「继续 vs 新开」的得失，判断是否该新开会话。**只评估不修改**任何会话文件。
核心原则：**压缩比例高 ≠ 该切换**；**窗口占比低 ≠ 经济无忧**。决策 = 继续成本（容量 + 质量 + 每轮 token 经济）vs 切换成本（丢失早期精确细节 + 交接轮次）的权衡。
## 何时使用
- **被动**：用户提到「压缩 / 新开会话 / 上下文开销 / context」时，立即完整评估。
- **主动**：长会话中用户持续推进（go / 继续 / 按计划推进）时，顺带检查一次；仅在**状态明显恶化或达到阈值**时提醒，否则一句「会话健康（压缩 x%）」带过。
## 硬约束
1. **只读评估**——不得修改任何工具的会话存储（Deep Code：`~/.deepcode/projects/`；Cursor：`~/.cursor/`；其他工具按适配层定位）。会话 JSONL / SQLite / 索引 / 快照一律只读。
2. **不夸大、不虚构**——数字来自实际文件统计；查不到就说明查不到，不猜。
3. **不机械建议切换**——必须评估工作性质与可恢复性；依赖早期内容的工作（重构/优化）即使压缩高也未必该切换。
4. **未达阈值不展开**——健康时一句话确认即可，完整报告只在达到阈值或用户要求时给。
5. **信号缺失走降级，不装精确**——工具适配层声明「能测什么、不能测什么」；缺失维度按降级规则处理（见「信号缺失降级规则」），不因缺数据默认健康或默认不健康。
## 工具适配层（数据来源入口）
本技能不硬编码任何工具的数据格式——每工具的读取方式集中在 **工具适配层**：
- **`references/tool-data-sources.md`**——已实现的工具适配节（Deep Code / Cursor）：会话目录定位、各信号读取命令、恢复能力入口。
- **`references/tool-adapter-template.md`**——新工具接入模板：按模板 + 探测流程为新工具生成适配节。
> **防双源**：SKILL.md 不写具体数据命令（命令会随工具版本漂移——见刷新机制）；命令一律只存在于 `references/tool-data-sources.md`。本页只留稳定方法论。
### 工具探测（确定当前跑在哪个工具上）
按以下优先级确认，取第一个可行的：
1. 会话上下文/环境变量已显式说明当前工具（如 agent 自知所在工具）→ 直接用。
2. 探测各工具会话存储目录，取**最近有写入**的那个（`ls -td` 按 mtime 排序比对）。
3. 仍不确定 → AskUserQuestion 问用户当前在哪个工具。
工具确定后，**查 `references/tool-data-sources.md` 对应适配节**执行数据获取。若当前工具未收录，走「新工具接入」流程（见文末 + 模板）。
### 信号可用性（决定能测什么 / 缺失走降级）
| 信号 | 含义 | 缺失时处理 |
|------|------|-----------|
| 消息数 | 当前会话消息/轮次数 | 无 → 定性（凭会话体感 + 工作性质）|
| 压缩/概要化比例 | 早期内容被概要化的程度 | 无 → 跳过该维度（不默认「未压缩」）|
| 上下文占用（绝对值）| 每轮历史输入 token 量 | 无 → 估算降级（消息数 × 单条估算）+ 标注 |
| 模型窗口（分母）| 判定占用比例的基准 | 查 `references/model-contexts.md`；未收录 → 问用户/网络核实 |
| 活跃度/时间跨度 | 会话新旧、持续时长 | 无 → 跳过 |
| 会话恢复能力 | 新会话能否找回旧上下文 | 无 → 按「仅 git + 交接文档」保守评估 |
Deep Code / Cursor 各自的信号可用性明细见 `references/tool-data-sources.md` 汇总表。
## 工作性质评估（切换成本——每次评估必答）
| # | 问题 | 回答为「是」→ 含义 |
|---|------|---------------------|
| 1a | 当前工作是否引用/修改**会话早期（压缩线以前）**的内容？（大型重构 / 优化 / 跨早期改动 = 是）| 依赖早期细节 → 切换丢失精确上下文 |
| 1b | （若 1a 是）依赖的早期**决策依据/命名约定/数字**是否已被交接文档/git/项目文档记录？| **否 → 隐性上下文丢失，切换成本极高**（有代码无理由）|
| 2 | 早期相关改动是否已 **commit/push**？| **否 → 禁止切换**（未提交=切换丢工作成果）|
| 3 | 交接文档 / 项目文档 / 工具的规则系统是否记录了早期关键决策？| 是 → 可恢复性好（新会话可找回）|
| 4 | 预计剩余工作量约多少轮对话？（1-2 轮 / 10-20 轮 / 数十轮）| 轮数多 → 继续会话的每轮历史输入费累积显著（切换省钱）|
- 切换成本 = 隐性上下文（#1b 否 → 极高）× 可恢复性（#2/#3 否 → 更高）× 任务中断（是否在任务边界——见「切换时点」）
- 独立新任务（#1a 否）→ 切换成本低
- **经济维度**（#4）：新开会话每轮输入 ≈ 只有新任务上下文（几 K token）；继续会话每轮输入 ≈ 上下文占用绝对值（历史）——轮数多时差距累积
- **同工具切换非冷启动**：Deep Code `/resume`、Cursor 历史面板均可列出历史会话继续，恢复成本 ≈ 交接轮次（读交接文档 + 首轮上下文建立），非「从零重建」
## 判定：二维决策模型
### 维度 A —— 继续成本（容量 + 质量 + 经济）
| 信号 | 阈值 | 成本 |
|------|------|------|
| 上下文占用窗口占比 | ≥ 50% 窗口 | 高（容量压力）|
| 上下文占用窗口占比 | 30%–50% 窗口 | 中 |
| 上下文占用窗口占比 | < 30% 窗口 | 低（容量充裕——大窗口下常如此）|
| 经济成本（绝对值 × 轮数）| 占用 ≥ 50K/轮 **且** 预计剩余 ≥10 轮 | 高（每轮历史输入费累积）|
| 经济成本 | 占用 ≥ 50K/轮 **或** 剩余 ≥10 轮 | 中 |
| 经济成本 | 其余（小历史 / 快收尾）| 低 |
| 压缩/概要化比例 | ≥ 50% | 中（早期细节概要化——**非容量危机**，git 可追溯）|
| 压缩/概要化比例 | 30%–50% | 低-中 |
| 消息数 | ≥ 800 条（代理指标，仅参考）| 低-中 |
多个信号取最严。**优先级**：经济成本（绝对值——与窗口无关，每轮都付）> 容量（窗口占比）> 压缩质量 > 消息数。
> 以上阈值为**默认参数**（按主流模型与成本结构校准）——可按项目实际调整。
> 窗口占比与绝对值的区别（以 deepseek-v4-flash 为例，窗口**查引用表**）：1M 窗口下 22 万占用 token 占比仅 22%（容量健康），但每轮输入仍按 22 万 token 计费（经济成本——若剩余轮数多，切换显著省钱；若服务端有 context caching，历史部分可能折扣价，差距缩小但仍存在）。窗口值一律查 `references/model-contexts.md`，不在正文写死。
>
> 估算口径：`activeTokens` 为索引**快照**；实际每轮输入 ≈ 压缩后的「摘要 + 未压缩消息」（可能小于快照）——经济评估用快照作上界估算，报告注明口径与方向（如「≤22 万/轮」）。
### 信号缺失降级规则（无 token 数据的工具——如 Cursor）
工具的适配层声明某信号不可得时，按此降级，**报告必须标注口径**：
| 缺失信号 | 降级做法 | 报告标注 |
|----------|---------|---------|
| 上下文占用（绝对值）| 估算 = 消息数 × 单条估算（0.5–2K token/条，按会话内容密度取）÷ 窗口（查表）→ 只给量级（低/中/高），不装精确；涉及切换决策时请用户看 UI 上下文占用条确认 | 「估算值（消息数 × 单条均值），请以 UI 为准」|
| 压缩/概要化比例 | 跳过该维度；用消息数 + 会话时长定性提示概要化风险 | 「不可量化（工具无压缩标记）」|
| 经济成本 | 无法量化 → 不计算，提示用户提供 UI 占用数后可算 | 「无法量化（无 token 快照）」|
| 活跃度/时间跨度 | 跳过 | — |
降级不等于默认健康：容量/经济维度标「未知（估算）」而非「低」。
### 维度 B —— 切换成本（工作性质 + 可恢复性）
| 情形 | 切换成本 |
|------|----------|
| 独立新任务，早期改动已 commit | 低 |
| 依赖早期内容，但已 commit + 交接文档有记录 | 中（可恢复但需交接）|
| 依赖早期内容，且早期改动未提交 | 极高（**禁止切换**）|
### 结论矩阵
| A 继续成本 \ B 切换成本 | B 低（独立任务）| B 高（依赖早期内容）|
|------------------------|----------------|---------------------|
| **A 低**（健康）| 🟢 继续 | 🟢 **继续**（切换反而亏——用 git/会话文件追溯早期细节）|
| **A 中** | 🟢 继续 | 🔵 继续，留意；如需切换先补交接（交接文档 + commit）|
| **A 高** | 🟡 **建议切换**（交接收割）| 🔴 **危险区**：深度交接（交接文档同步早期状态 + commit 后）再切换，或继续+git 追溯 |
## 切换时点建议（降低中断成本）
切换成本与「时点」强相关：
- **任务边界处切换最划算**：一个 commit / 阶段完成、无进行中的推理链 → 中断损失 ≈ 0，交接成本最低
- **任务中间切换最亏**：推理链进行中、半成品未落地 → 切换=打断思路 + 隐性状态丢失
- 主动触发时若处于任务中间：建议「先收尾（commit / 写交接文档）再切换」，不裸切
## 输出格式
### 达到阈值时（🟡/🔴/🔵）
```
## 会话健康度评估
| 指标 | 当前值 | 判定 |
|------|--------|------|
| 压缩比例 | 65%（714/1100）| 🔵 概要化（非容量危机——git 可追溯）|
| 消息数 | 1100 条 | 🔵 代理指标 |
| 上下文占用 | 221,648（窗口 22%——容量低 / 绝对值高）| 🟢 容量 / 🟡 经济 |
（Cursor 等无 token 数据的工具：相应行改为「估算值 / 无法量化」并标注，见信号缺失降级规则。）
工作性质评估：
- 依赖早期内容？是/否（重构/优化说明）
- 早期改动已 commit？是/否（未提交 → 禁止切换）
- 交接文档记录？是/否
- 预计剩余轮数？N 轮（× 占用/轮历史输入费 = 继续成本估算；新会话 ≈ 几 K/轮）
→ 切换成本：低/中/极高；经济结论：继续 / 切换省钱
**结论**：（按矩阵——建议切换 / 继续但留意 / 危险区需深度交接）
交接就绪检查（建议切换时）：
- [ ] git 工作树干净 / 未提交变更数
- [ ] 关键产出已 push（最新 commit hash）
- [ ] 交接文档存在且同步到最新
- [ ] 运行中进程？（dev server / LSP / 测试服务——切换前说明归属/清理）
- [ ] 会话内临时状态？（临时配置 / 未持久化改动——是否需记录）
- [ ] 测试状态（若项目有质量链）
新会话入口：（按工具——Deep Code：输入「<项目名> 接手」走 project-intake 或 /resume；Cursor：历史面板 + 项目 rules 文件）
```
### 健康时（🟢）或切换反而亏时
> 会话健康（压缩 12%）——继续。
> 或：压缩 65% 但当前重构依赖早期 commit（已提交，可 git 追溯）——**切换反而亏，建议继续**。
## 交接就绪检查命令（建议新开会话时）
```bash
git status --short | head -5                     # 未提交变更
git log --oneline -1                              # 最新 commit
ls HANDOFF.md 2>/dev/null && echo "HANDOFF 存在"  # 交接文档
```
检查失败项（如未提交变更）→ 提醒先提交或说明不切换。
## 反模式
- 修改/删除任何工具会话存储下的文件（只读评估）
- 不看实际数字就凭「感觉很长」建议新开会话
- 不看工作性质机械建议切换（重构依赖早期内容时切换反而亏）
- 只看窗口占比忽略绝对值（1M 窗口下 22% 容量健康 ≠ 每轮 22 万 token 免费）
- 剩余 1-2 轮仍建议切换（交接本身 1-2 轮成本，省不下）
- 早期改动未提交 git 仍建议切换（丢工作成果）
- 任务中间裸切（推理链进行中——先收尾再切）
- 忽略运行中进程/临时状态就建议切换（dev/LSP/test 归属不明）
- 建议新开会话却不给交接就绪检查（让用户裸切换）
- 虚构 token 数 / 窗口大小（查不到就说「索引无该字段」或注明估计）
- 把 token 快照当精确每轮成本（应注明「≤上界」口径）
- **Cursor 等无 token 数据的工具仍编造占用数字**（应走估算降级 + 标注，或请用户看 UI）
- **以「工具无压缩标记」默认未压缩**（应跳过维度并说明不可量化）
- **在 SKILL.md 正文写死数据命令**（命令只存 references/tool-data-sources.md，防版本漂移）
## 完成标准
- [ ] 只读：未修改任何会话/索引/快照文件
- [ ] 数字来自实际文件统计（wc/jq/sqlite3），非估算；估算处明确标注口径
- [ ] 工具已确认（工具探测），数据按适配层执行
- [ ] 工作性质 5 问必答（依赖度 1a/记录完整性 1b/提交状态/交接文档/剩余轮数）——切换成本与经济有依据
- [ ] 结论按二维矩阵给出（继续成本 × 切换成本），非机械阈值
- [ ] 经济评估：窗口占比（容量）与绝对值（每轮成本）分别判；注明快照口径（≤上界）或标注「无法量化」
- [ ] 信号缺失按降级规则处理并标注，不装精确
- [ ] 切换建议含时点判断（任务边界 vs 任务中间——是否需先收尾）
- [ ] 达到阈值时含交接就绪检查（含进程/临时状态）；健康或切换反而亏时说明理由
- [ ] 新会话入口指引明确（按工具：/resume / project-intake / 历史面板 + rules）
## 新工具接入（在其他工具中使用本技能）
1. 将本技能目录复制到该工具的 skills/rules 位置。
2. 打开 `references/tool-adapter-template.md`，按「接入流程」对该工具做只读探测。
3. 按模板生成该工具的适配节，追加到 `references/tool-data-sources.md`（含 lastUpdated + refreshInterval + 置信度）。
4. 更新 `references/tool-data-sources.md` 的信号可用性汇总表。
5. 本 SKILL.md **无需改动**（方法论与工具无关）；若工具行为变化，只刷新对应适配节。
> 提示：Cursor 场景除 skills 外，还可将精简版健康度检查要点写入项目 `.cursor/rules/*.mdc` 以便常驻触发——内容从「何时使用」+「硬约束」+「切换时点」提炼即可。