NinjaSln-labs/dsh-context-compass

dsh-context-compass

npm version
License
GitHub stars

DeepSeek Harness 的上下文罗盘插件：基于真实数据的「继续 vs 新开会话」指示器。

- 头部徽章 — 会话日志按钮旁的有色圆点 + 边框（绿/蓝/黄/红），使用 DSH 主题令牌。响应式：完全由宿主计算的 sessionHealth 投影驱动（推送帧——这是社区插件唯一可用的线上数据通道；客户端 Remote 是构建期固定清单，因此本插件无 Remote、无轮询）。悬停显示建议、窗口占用条、每轮 token 成本与缓存命中率（命中率是上下文稳定度的表现；压缩会重置命中）、压缩感知的预计下次输入（剔除缓存命中）、计费预期（金额）（zh 界面显示 CNY，否则 USD——官方峰谷定价，标注 忙时价/闲时价）、模型窗口、会话规模与压缩次数（含上次压缩比例——按压缩前后压力快照差值推断，标「快照口径」）。压缩后判定滞后（severity 判定基于压缩前压力、占用条已按下次请求重估）时提示「下次请求后更新」。占用条下方有占用趋势 sparkline（v0.9.0：最近 ≤40 次请求的压力采样迷你折线，归一当前窗口——一眼看出稳步上升 vs 压缩后回落；少于 2 次采样隐藏）。点击运行 /compass 查看完整报告。支持键盘操作。
- /compass 命令 — 完整文本报告，可选探测：
- /compass — 全部（git / 交接文档探测，可配置；进程探测默认关闭，见下）
- /compass minimal — 仅核心指标（token / 窗口 / 规模）
- /compass no-git / /compass no-handoff — 跳过某项探测
- /compass doc= — 检查你自己的交接文档（不预设文件名；概念是你的，名字也是你的）
- /compass remaining= — 费用预期（金额）：每轮成本 × 剩余轮数 ≈ 预计输入花费（含缓存折扣）
- /compass processes — 强制进程探测
- context_compass 工具 — 模型可调用的只读评估（长任务自查）：结构化结论（severity / recommendation / signals / cost / handoffReady），黄/红档附带完整 markdown 报告。工作性质问题由模型自查（dependsOnEarly / earlyDecisionRecorded / remainingRounds），其余全部由宿主精确测量。
- sessionHealth 投影 — 宿主计算的持久折叠（轮次、消息数、压缩次数、last-wins 压力/窗口、上次请求缓存桶、上次压缩比例、severity + 建议）推送到所有客户端；重放与页面刷新后依然存活。
- 多会话罗盘一览面板（v0.6.0，0.7.15–0.7.17 重构）— 侧栏底部「设置」旁的「罗盘一览」按钮打开全屏面板（shell.overlay），列出所有会话的健康判定。数据走同源宿主 RPC（/context-compass-rpc，仅 loopback）：在线会话切投影注册表快照，冷会话读持久化投影缓存（异步 cold load 兜底）；标题来自日志折叠 / 批量查询。行按运行中置顶排序：运行中组内红→黄→蓝→绿 → 非运行中同梯（红→黄→蓝→绿→无数据）→ 已加载>冷却 → 新会话在前（host+client 双侧同规则）。面板打开期间每 5 秒轮询，stale-while-revalidate：过期帧立即返回旧列表 + 后台刷新，任何帧都不等慢查询（实测轮询帧 ≤20ms，冷启动首帧唯一例外）。状态列三态——运行中（智能体正在处理回回合，与侧栏「进行中」同源）、已加载（内存驻留待命）、冷却（仅持久化）；「活动」列显示相对时间。点击行打开该会话并运行 /compass。Esc / 点遮罩关闭；键盘与读屏可达（severity 从不只靠颜色传达）。
- 压缩比例与判定滞后标注（v0.7.0）— 折叠在 compaction/end 前后的压力快照上推断上次压缩比例（1 − 压缩后/压缩前，不依赖事件载荷；不可判定的折叠读 null，绝不虚报 0），并在建议、报告、工具信号与面板浮层以「快照口径」标注。压缩后若 severity 判定（last-wins 压力）与占用条（压缩感知的下次请求成本）分叉 ≥5pp，浮层标注滞后提示，直到下次请求刷新判定。

交接清单（自动化）

黄/红档时，/compass 追加真实状态清单而非静态文案：git status --short / git log --oneline -1 / git status -sb（经 ctx.subprocess 的只读白名单 argv）驱动 commit/push 项，交接文档探测驱动文档项，进程探测驱动进程项。无法检查的项标记 [ ] 并说明原因——绝不静默显示「已完成」。

知识库联动（解耦，v0.7.2）

不绑定任何特定知识库插件（未装则跳过）：

- /compass 报告尾部附结构化交接快照段（固定键名 context-compass-handoff-snapshot：severity / recommendation / compacted / compression_ratio / uncommitted / handoff_ready / timestamp）——纯文本、可 grep，任何记忆/知识插件或用户都能摄取（如 knowledge_write 存入库）。
- 可选探测 ctx.get('knowledge')：存在（如 dsh-knowledge-sqlite）则在新会话用其只读 search() 检索历史快照，给 /compass 加一段「跨会话回顾（上次会话 severity/交接就绪…）」；不存在则 probe 一行「知识库未安装，跳过」。写入面留给用户/模型显式调用（自带 ask 门控），插件不越权。

判定模型

二维「继续 vs 切换」（社区 session-health 方法论），参数在插件配置中：

| 档位 | 条件（默认） | 建议 |
|---|---|---|
| 绿 | 窗口占比 ": { "peak": { "inputMissPerMCny": 3.0, "inputHitPerMCny": 0.10, "inputMissPerMUsd": 0.44, "inputHitPerMUsd": 0.014 }, "offpeak": { ... } }, "*": { ... } } }

为什么用真实数据

每个信号都来自 harness 本身——无任何估算：

| 信号 | 来源 |
|---|---|
| 每轮输入 token | ctx.tokenMeter.measure（精确，快照口径） |
| 上下文窗口 | llm.resolveModelInfo（如 deepseek-v4-pro 的 1M） |
| 消息 / 轮次 / 压缩次数 / 缓存桶 / 压缩比例 | sessionHealth 投影折叠（sessionQuery 兜底；压缩比例 = 折叠内 1 − 压缩后/压缩前压力快照，快照口径） |
| 下次请求占用 | token-meter contextPressure.projectedTokens（压缩感知） |
| git 仓库 + 工作树状态 | fs 探测 + 只读 git 子命令 |
| 交接文档 | 探测你提供的文件名 |
| 运行中进程 | ctx.subprocess 只读 ps 探测，按工作区过滤（默认关闭——/compass processes 或配置启用） |

安装

dsh plugin add dsh-context-compass
然后重启 / 重载挂载它的 profile

或加入 profile 补丁层：

你的 profile cordis.patch.yml
- insert:
- id: context-compass
name: 'dsh-context-compass'

开发

npm run build      # tsc → lib/ + esbuild 客户端 bundle
npm run typecheck  # 严格类型检查
npm run smoke      # 逻辑冒烟测试（stub 服务）
npm run mount      # 真实 cordis 挂载测试（命令 + 工具 + 投影）
npm run build:client && node scripts/client-mount.mjs  # 浏览器启动路径测试
npm run visual     # Playwright 视觉回归（只读，不污染会话：panel RPC mock 矩阵 明/暗×四档×分页 + 徽章 hover 桥接层 e2e）
npm run visual:update  # 有意变更视觉后重写基线（visual/baselines/）

设计

方法论源自社区 session-health 技能（二维继续-vs-切换模型）；harness 版本把数据层从估算升级为精确测量。完整设计笔记（信号映射、判定模型、可配置检查项）见 docs/DESIGN.md；后续路线图见 docs/ROADMAP.md。

⭐ 支持

如果这个插件对你有帮助，欢迎到 GitHub 仓库 点个 ⭐ Star——它是我持续维护的动力。也欢迎提 issue / PR 一起改进。

License

MIT