dsh-context-ops
DSH 上下文运维插件：交接技能 + 上下文决策/诊断技能 + 压力读数工具（含窗口证据来源）+ 斜杠命令。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:OnebugIS/dsh-context-ops#05bd19ceb75c0f7f70ef4fc4afe52653c740d3ccContext Ops 以 dsh-context-ops 发布，当前版本为 0.1.6。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
给 DeepSeek Harness（dsh）的上下文管理插件：
交接、压缩决策、上下文诊断三个技能 + 自包含压力读数工具 + 三个斜杠命令 + 压力 toast 提醒（Web Client 角标）。
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 | 自包含读数 + 窗口证据（windowSource / routeKey） |
| 历史/复盘工具 | context_history | lib/index.js | 峰值、最后一次输入侧 token、压缩尝试/成功/失败次数 |
| 斜杠命令 | /handoff /pressure /diagnose | lib/index.js | 显式触发对应技能（commands 服务缺失时自动跳过） |
| 压力 toast（可选） | enableReminder | client.js + 投影 | Web Client 右上角角标：remindAt 建议压缩、handoffAt 建议交接；60 秒自动收起，发起压缩立即收起 |
| 压缩摘要走强模型 | 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"
context-handoff触发：交接、收尾、存档、checkpoint、handover、续接项目、继续昨晚的项目。
产出：CHECKPOINT.md 五行表——目标、现状、下一步、未决、证据。
什么时候不用：1–2 轮小任务、纯问答无项目状态、用户明确说不用。
context-decision触发：上下文管理、该压了吗、要不要交班、上下文怎么办、压力多少、还有多少余量。
流程：先调 context_pressure 拿真实数字，再按阶梯给一句处方（做什么 + 为什么 + 依据哪个数）；能压时把 /compact 复制到剪贴板（macOS pbcopy，其他平台提示手输），不能压时建议走交接。
context-diagnose触发：上下文诊断、诊断一下、上下文体检、体检、ctx-check、帮我看看上下文。
产出：一份诊断报告（现状 / 落档 / 能压吗 / 处方 / 告警）；能压时复制 /compact 到剪贴板，不能压时建议交接。
context_pressure无参数调用，返回：
{
"pressureTokens": 82341,
"surfaceTokens": 71022,
"window": 800000,
"declaredWindow": 1048576,
"realWindow": 800000,
"windowInflated": true,
"windowSource": "override",
"routeKey": "zicode/deepseek-v4-pro",
"pct": 10.3,
"cacheHitRate": 0.995,
"provider": "zicode",
"model": "deepseek-v4-pro",
"note": ""
}
| 字段 | 含义 |
|---|---|
pressureTokens | 请求体总 token（判断压缩的真实口径） |
surfaceTokens | 对话面 token |
window | 有效上下文窗口 = min(declaredWindow, realWindow)；未知时 null |
declaredWindow | 路由 / profile 声明的窗口；未知时 null |
realWindow | 该路由的容量上限估计：配置的实测值优先，否则退回内置标称值（型号通用规格，不代表当前线路实测支持）；都未知时 null |
windowInflated | 声明窗口高于插件认定的上限（declaredWindow > realWindow）；含义随 windowSource 不同，见下 |
windowSource | 这个窗口数字的依据：override 实测配置 / nominal 内置标称 / declared 只有声明值 / unknown |
routeKey | 本会话路由键 provider/model，即 realWindows 里该用的键 |
pct | 占用百分比 = pressureTokens / window * 100；窗口未知时 null |
cacheHitRate | 读取缓存占输入缓存桶的比例（0–1）= cacheReadTokens / (cacheReadTokens + cacheWriteTokens + uncachedInputTokens)；未知时 null |
provider / model | 当前路由的 provider / model；未知时为空串 |
note | 读数失败时的错误说明；正常为空串 |
windowInflated是「声明窗口超过插件认定的上限」的信号，含义随windowSource变：
windowSource=nominal：声明值高于型号标称值。宿主按声明窗口算自动压缩触发点，所以可能永远压不到 —— 属真·虚高，改 profile 或补实测值。windowSource=override：声明值高于你在这条线路的实测安全值。pct 已按实测值算，但宿主自动压缩仍按声明值算，触发点会比实测墙更晚。这时根治是把 profile 的contextWindow也改成实测值 —— 只填realWindows只修正了报告，没改宿主行为。反过来把大窗口模型特意配小（如 1M 模型限到 128k）是合法限制：
windowInflated=false，window就是那个小值，不会被放大。
⚠ 两把尺子：
pct的分母是window（可能被实测值收窄），宿主自动压缩的分母是declaredWindow（声明值）。所以window被收窄后，别用「pct 已过 80% 而宿主没压」去推断自动压缩出了问题。
插件不判断你的 provider 是官方还是中转。
provider只是 profile 里的键名，插件看不到 baseURL，也不该猜：同一个型号在不同线路上容量可以不同（手册 §1.5）。所以windowSource=nominal只说明「这个数字来自内置标称值、尚未在本线路实测」，不等于「你走的是中转」。想让 pct 按真实容量算，就在
realWindows里按provider/model填一条实测安全值（用针尖测试，手册 §1.6；取实测值的 ~80%，手册 §1.2）。没填的线路一律退回标称值，行为和旧版一致。
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 表示具备尝试压缩条件；不等于现在执行一定成功。摘要模型、输出预算、网关 body 限制、超时和“摘要没有变小”等因素仍可能导致失败。
⚠ 但这张表不是宿主的阈值。 DSH 自己的 compaction-basic 默认在
min(contextWindow × 0.8, contextWindow − 预留 output − 65536) 就自动压缩——
1M 窗口在无额外 output 预留时约 838k（80%）；131k 窗口受 64K headroom 限制时上限约 65,536，实际还可能因 output 预留更低。也就是说正常自动模式下，「85% 才准备交接」这一档
通常轮不到人动手：等你看到 85%，压缩早已发生。本插件的阶梯是建议，不改变宿主行为；
要改触发点，去 profile 里配 compaction-basic 的 thresholdRatio / headroomTokens。
压缩失败三归因：
context overflow → 换大窗口模型再压，或交班；stream idle timeout → 别重试，直接交班；summary is not smaller → 已到极限，忽略；要降只能新会话。flowchart LR
subgraph DSH["DSH Runtime"]
S[skills registry]
T[tools registry]
C[commands]
M[tokenMeter]
PR[contextPressure 投影]
end
subgraph W["Web Client"]
SL[conversation.input.dock slot]
BN[压力 toast（client.js）]
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"]
RC["contextOpsReminderConfig 投影"]
CS["contextOpsCompactionSignal 投影"]
end
H --> S
D --> S
G --> S
PT --> T
HT --> T
PT --> M
CM --> C
RC --> PR
CS --> PR
BN --> SL
BN -.读投影.-> RC
BN -.读投影.-> CS
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 | 压力 toast：Web Client 右上角显示「建议 /compact / 建议交接」角标（见下） |
remindAt | 85 | 提醒阈值百分比（50–95） |
handoffAt | 92 | 交接提示线百分比（50–95，必须 ≥ remindAt）；压力 ≥ 此值时暂停任务、展示 brief 并请求确认，不会绕过确认自动写盘 |
realWindows | {} | 按 provider/model 填的实测安全窗口，见下 |
未知键直接报错（unknown config key）；已知键类型写错（如 enableReminder: "true"、remindAt: "70"）也报错，不静默取反或回落。
realWindows（可选）内置表只是型号标称值：同一个型号经不同线路/代理，容量可能不一样，所以标称值不能代表你的线路真能吃下。要按实测算 pct，就按 provider/model 填一条：
- id: context-ops
name: 'dsh-context-ops'
config:
enablePressureTool: true
enableCommands: true
enableReminder: false
remindAt: 85
handoffAt: 92
realWindows:
zicode/deepseek-v4-pro: 800000
zicode/glm-5.3: 600000
deepseek-account/deepseek-v4-pro: 1048576
规则：
provider/model）。只写型号会报错——同一型号在不同线路容量不同，按型号覆盖会把一条线路的实测值错用到另一条上，比不填更糟。context_pressure 返回的 routeKey，不用自己拼。min(声明窗口, 实测值)：声明偏小时以声明为准，实测值不会把窗口放大。⚠ 注意 DSH patch 的语义是同 id 整段替换 config，不是合并：在 profile 里覆盖
context-ops这一行时，其它键也要一起写全，否则会打回默认值。
开启 enableReminder 后，Web Client 会在当前会话右上角显示一条压力角标（toast）：
remindAt（默认 85%）→ 黄色：「上下文已达 85%，建议 /compact」；handoffAt（默认 92%）→ 红色：「上下文已达 92%，建议立即交接」。sessionId + 档位 记在 localStorage，组件重挂载 / 重启 App 不会重新计时，关闭 App 期间走完的截止时间也不会复活。compaction/start），Client 收到信号就立刻收起当前 toast，不等 60 秒；压缩导致的降档不换档重弹，等有效读数确实回落后重新武装。projectedTokens（下一次请求的估算，压缩后先回落），缺失时回退到 pressureTokens。contextPressure + 插件自己的 contextOpsReminderConfig / contextOpsCompactionSignal），不追加 Session 事件、不伪造 user 消息，不会越提醒越占上下文。enableReminder: true 才生效；阈值（remindAt / handoffAt）改 profile 即可，Client 每次按当前配置现算，不会被旧会话缓存卡住。| 场景 | 行为 |
|---|---|
tokenMeter 缺失 | 跳过两个工具（读数没数据源），三个技能照常注册 |
commands 缺失 | 只跳过斜杠命令，技能与工具照常 |
| Web Client / 投影缺失 | toast 不显示，技能与工具照常；读数恢复后不复活已退出的提醒 |
| 无会话调用工具 | 返回空值 + note: no session（pressureTokens 仍是 0，所以必须看 note） |
| 读数失败 | 返回空值 + note 错误说明，不把读数故障变成对话故障 |
| 提醒求值失败 | toast 不显示，并留一条 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 上下文诊断技能
├── client.js Web Client 入口：压力 toast（conversation.input.dock slot）
├── locale/ 双语 metadata（en/zh）
├── assets/ README 配图（hero、ladder）
├── test/ node --test 单元测试
├── cordis.patch.yml 自注册入口
├── icon.svg 插件图标
├── CHANGELOG.md 更新日志
├── package.json dsh.bundle + dsh.client 声明，依赖 zod
└── README.md
| 项 | 要求 |
|---|---|
| Node.js | >= 20 |
| DSH | 0.2.x（使用 ctx.skills.register / ctx.tools.register / ctx.commands.register / tokenMeter / session 投影 / dsh.client Web Client 入口） |
| 运行时依赖 | 1（zod，投影 schema 校验） |
| 存储改动 | 无（不改 DSH 存储 schema，可回滚） |
# 单元测试（node 内置 test runner，无需额外依赖）
npm test
# 语法自检
node --check lib/index.js
# 本地装到某个 profile
dsh plugin --profile <profile> add "$(pwd)"
见 CHANGELOG.md。
MIT © 廷宇