dsh-context-ops · 上下文运维

给 DeepSeek Harness（dsh）的上下文管理插件：
交接、压缩决策、上下文诊断三个技能 + 自包含压力读数工具 + 三个斜杠命令。

A DeepSeek Harness plugin for context management: handoff, compaction decision and diagnosis skills, a self-contained pressure tool, and slash commands.

English: README.en.md

---

为什么需要它

你遇到的问题	这个插件怎么解
会话越聊越慢，不知道什么时候该压	「该压了吗」→ 调 context_pressure 拿数 → 套阶梯 → 一句处方
压完还是丢约束 / 压不动，不知道为什么	「上下文诊断」→ 逐层核对 + 硬判据 + 压缩失败三归因
换天、换会话要重读旧聊天	「交接」→ 5 行 brief 写到 CHECKPOINT.md，替代重读
读数依赖某台机器的外部脚本	context_pressure 工具读 DSH 自带 tokenMeter，装哪儿都能用
换模型后立刻压还是走旧模型	诊断技能明确提示：先跑一轮普通对话再 /compact

能力一览

能力	名称	实现	说明
交接技能	context-handoff	lib/skills/handoff.js	产出 5 行 brief（目标/现状/下一步/未决/证据）到 CHECKPOINT.md
上下文决策技能	context-decision	lib/skills/decision.js	读数 → 套阶梯 → 给一句处方
上下文诊断技能	context-diagnose	lib/skills/diagnose.js	一次体检，逐层核对，给完整诊断报告
压力读数工具	context_pressure	lib/index.js	自包含读数，数据来自 DSH 自带 tokenMeter
历史/复盘工具	context_history	lib/index.js	峰值、最后一次输入侧 token、压缩尝试/成功/失败次数
斜杠命令	/handoff /pressure /diagnose	lib/index.js	显式触发对应技能（commands 服务缺失时自动跳过）
主动提醒（可选）	enableReminder	lib/index.js	压力过阈值时把一句提示挂进宿主「运行时上下文」快照，不伪造 user 消息
压缩摘要走强模型	compaction-basic 配置	文档化（见下）	走 DSH 原生字段，本插件不写死任何账号/模型

快速开始

# 1) 安装（把 <profile> 换成你的 profile，如 desktop / web）
dsh plugin --profile <profile> add dsh-context-ops

# 2) 重启 DSH（改 profile 必须重启才生效）

# 3) 选一个触发词试试
#    「交接」 / 「该压了吗」 / 「上下文诊断」
#    或直接用斜杠命令：/handoff  /pressure  /diagnose

本地开发安装：

dsh plugin --profile <profile> add "file:/绝对路径/dsh-context-ops"

三个技能

1) 交接 context-handoff

触发：交接、收尾、存档、checkpoint、handover、续接项目、继续昨晚的项目。

产出：CHECKPOINT.md 五行表——目标、现状、下一步、未决、证据。

什么时候不用：1–2 轮小任务、纯问答无项目状态、用户明确说不用。

2) 上下文决策 context-decision

触发：上下文管理、该压了吗、要不要交班、上下文怎么办、压力多少、还有多少余量。

流程：先调 context_pressure 拿真实数字，再按阶梯给一句处方（做什么 + 为什么 + 依据哪个数）；能压时把 /compact 复制到剪贴板（macOS pbcopy，其他平台提示手输），不能压时建议走交接。

3) 上下文诊断 context-diagnose

触发：上下文诊断、诊断一下、上下文体检、体检、ctx-check、帮我看看上下文。

产出：一份诊断报告（现状 / 落档 / 能压吗 / 处方 / 告警）；能压时复制 /compact 到剪贴板，不能压时建议交接。

压力读数工具 context_pressure

无参数调用，返回：

{
  "pressureTokens": 82341,
  "surfaceTokens": 71022,
  "window": 131072,
  "declaredWindow": 131072,
  "realWindow": 1048576,
  "windowInflated": false,
  "pct": 62.8,
  "cacheHitRate": 0.995,
  "provider": "zicode",
  "model": "deepseek-flash",
  "note": ""
}

字段	含义
pressureTokens	请求体总 token（判断压缩的真实口径）
surfaceTokens	对话面 token
window	有效上下文窗口 = min(declaredWindow, realWindow)；未知时 null
declaredWindow	路由 / profile 声明的窗口；未知时 null
realWindow	该模型真实上限（内置窗口表）；型号不在表里时 null
windowInflated	窗口虚高 = declaredWindow > realWindow；无法判断时 null
pct	占用百分比 = pressureTokens / window * 100；窗口未知时 null
cacheHitRate	缓存命中率（0–1）= cacheReadTokens / (cacheReadTokens + uncachedInputTokens)；未知时 null
provider / model	当前路由的 provider / model；未知时为空串
note	读数失败时的错误说明；正常为空串

windowInflated 是「自动压缩永不触发」的元凶检测：把 1M 模型配成 2M 时，声明窗口虚高、pct 永远压不到 50%，/compact 也永远不会自动来。工具按真实上限收紧 window 并给出告警，改 profile 才是根治。

反过来把大窗口模型特意配小（如 1M 模型限到 128k）是合法限制：windowInflated=false，window 就是那个小值，不会被放大。

cacheHitRate 高（接近 1）= 前缀被复用，便宜且首 token 快；持续偏低说明上下文在不断被改写（或 provider 不支持缓存），是「该换会话/重开」的信号。 注意它是全会话累计：第一次冷请求必然 0% 命中，会话越长越被历史稀释。

windowInflated = null 有两种情况：型号不在内置窗口表里，或这个会话还没有过路由窗口记录。都表示「无法判断」，不要当成 false 当作安全。

判断压缩时用 pressureTokens ÷ window，不要用界面显示的 projectedTokens（偏低）。

历史复盘工具 context_history

无参数调用，返回会话级的趋势与压缩记录：

字段	含义
peakTokens / lastTokens	历史峰值 / 最后一次请求的输入侧 token（input + cacheRead + cacheWrite，不含输出）
compactionCount	压缩尝试次数（compaction/start）
compactionSuccess	压缩成功次数（compaction/summary）
compactionError	压缩失败次数（compaction/end 且带 error）

peakTokens 和 context_pressure.pressureTokens 不是同一把尺子：后者含输出预算与工具/系统提示，系统性更大。趋势可以比，两个数不能相减。

失败为什么这么算：宿主只有 compaction/start / summary / end 三种落盘事件，失败记在 compaction/end.data.error 上；compaction/summary-error 只是内存里的 waterfall 钩子名，不落盘，数它永远是 0。

斜杠命令

命令	等价触发	作用
/handoff	「交接」	进入 5 行 brief 流程
/pressure	「该压了吗」	调 context_pressure 给处方
/diagnose	「上下文诊断」	一次完整体检

决策阶梯

硬判据：能压缩 ⇔ pressureTokens < window × 0.95。

⚠ 但这张表不是宿主的阈值。 DSH 自己的 compaction-basic 默认在 min(contextWindow × 0.8, contextWindow − 预留 output − 65536) 就自动压缩—— 1M 窗口约 838k（80%）、131k 窗口约 105k。也就是说正常自动模式下，「85% 才准备交接」这一档 通常轮不到人动手：等你看到 85%，压缩早已发生。本插件的阶梯是建议，不改变宿主行为； 要改触发点，去 profile 里配 compaction-basic 的 thresholdRatio / headroomTokens。

压缩失败三归因：

1. context overflow → 换大窗口模型再压，或交班；
2. stream idle timeout → 别重试，直接交班；
3. summary is not smaller → 已到极限，忽略；要降只能新会话。

架构

flowchart LR
    subgraph DSH["DSH Runtime"]
        S[skills registry]
        T[tools registry]
        C[commands]
        M[tokenMeter]
        SP[systemPrompt.context]
    end
    subgraph P["dsh-context-ops"]
        H["context-handoff"]
        D["context-decision"]
        G["context-diagnose"]
        PT["context_pressure"]
        HT["context_history"]
        CM["/handoff · /pressure · /diagnose"]
        RM["压力提醒（可选）"]
    end
    H --> S
    D --> S
    G --> S
    PT --> T
    HT --> T
    PT --> M
    CM --> C
    RM --> SP
    RM --> M

flowchart TD
    A["用户：该压了吗 / 上下文诊断"] --> B["调 context_pressure 拿数"]
    B --> C{"能压缩吗？<br/>pressureTokens < window × 0.95"}
    C -- 能 --> D["按阶梯给处方"]
    C -- 不能 --> E["走交接 / 换大窗口模型"]
    D --> F{"处方是动作？"}
    F -- 是 --> G["复制 /compact 到剪贴板（或提示手输）"]
    F -- 否 --> H["只给结论"]
    G --> I["用户粘贴 /compact 执行，或触发交接"]

插件配置

键	默认	说明
enablePressureTool	true	是否注册 context_pressure + context_history 两个工具（需要 tokenMeter，缺失时自动跳过）
enableCommands	true	是否注册 /handoff /pressure /diagnose（需要 commands，缺失时自动跳过）
enableReminder	false	主动提醒：压力 ≥ remindAt 时，把一句提示挂进宿主「运行时上下文」快照
remindAt	85	提醒阈值百分比（50–95）
handoffAt	92	强制交接线百分比（50–95）；压力 ≥ 此值时提醒升级为「自动执行交接」

未知键直接报错（unknown config key）；已知键类型写错（如 enableReminder: "true"、remindAt: "70"）也报错，不静默取反或回落。

主动提醒（可选）

开启后，每次装配请求时求值一次：pct ≥ remindAt 就把一句 system-reminder 挂进宿主的 运行时上下文快照（ctx.systemPrompt.context()）。

• 两档行为：
  • pct ≥ remindAt（默认 85%）→ 建议压缩或交接；
  • pct ≥ handoffAt（默认 92%）→ 强制交接：提醒模型「上下文压力已过交接线，我现在自动执行交接、写出 CHECKPOINT.md」，先落盘再继续，避免等额度耗尽。
• 不伪造 user 消息：这是关键。走 agent/pre-step 往 decision.messages 里塞消息看着像「不落盘」， 但宿主 step() 会把每一条非 runtime-context 的消息 session.append('user/message') —— 提醒会进会话历史、出现在对话里、之后每个请求都重发，等于上下文插件自己给自己加压力。
• 只按档位变文案：文本里不带精确百分比和 token 数（那会让快照每轮重写）。跨档（85 → 95）才变； 压力回落自动消失。
• 可忽略：文案带「可忽略」，不影响正常对话；要精确数字让它调 context_pressure。
• 默认关闭：enableReminder: true 才生效。

健壮性

场景	行为
tokenMeter 缺失	跳过两个工具（读数没数据源），三个技能照常注册
commands 缺失	只跳过斜杠命令，技能与工具照常
systemPrompt 缺失	只跳过主动提醒，其余照常
无会话调用工具	返回空值 + note: no session（pressureTokens 仍是 0，所以必须看 note）
读数失败	返回空值 + note 错误说明，不把读数故障变成对话故障
提醒求值失败	返回空串（不注入），并留一条 warn 日志，不静默吞掉代码错误

配置：压缩摘要走强模型（可选）

本插件不写死 provider/model。如需把 /compact 的摘要路由到指定模型，在你自己的 profile cordis.patch.yml 里给 compaction-basic 配（DSH 原生字段）：

- id: compaction-basic
  config:
    summarizationProvider: deepseek-account   # 换成你自己的 provider
    summarizationModel: deepseek-v4-pro       # 换成你自己的 model

两个字段要么都空（默认 = 用当前会话模型），要么都填，否则 compaction-basic 会拒载。

压缩前预处理（DSH 已自带并默认挂载）：compaction-tool-result-pruner（裁剪超大工具结果，模型无关）+ compaction-image-offload（超预算图片换成占位符重试）在 /compact 时自动参与——先裁剪/卸载，再由摘要模型压。无需本插件额外配置。

项目结构

dsh-context-ops/
├── lib/
│   ├── index.js          入口：注册技能 + 两个工具 + 斜杠命令 + 可选提醒
│   ├── policy.js         统一策略常量（阶梯/宿主阈值/硬判据/三归因/真实窗口）
│   └── skills/
│       ├── handoff.js    交接技能
│       ├── decision.js   上下文决策技能
│       └── diagnose.js   上下文诊断技能
├── locale/               双语 metadata（en/zh）
├── assets/               README 配图（hero、ladder）
├── test/                 node --test 单元测试
├── cordis.patch.yml      自注册入口
├── icon.svg              插件图标
├── CHANGELOG.md          更新日志
├── package.json          无依赖，dsh.bundle 声明
└── README.md

兼容性

项	要求
Node.js	>= 20
DSH	0.2.x（使用 ctx.skills.register / ctx.tools.register / ctx.commands.register / tokenMeter）
运行时依赖	0（纯 ESM，仅用 node:crypto）
存储改动	无（不改 DSH 存储 schema，可回滚）

开发与测试

# 单元测试（node 内置 test runner，无需额外依赖）
npm test

# 语法自检
node --check lib/index.js

# 本地装到某个 profile
dsh plugin --profile <profile> add "$(pwd)"

更新日志

见 CHANGELOG.md。

License

MIT © 廷宇