dsh-context-ops

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

为什么需要它

能力一览

快速开始

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

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

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

本地开发安装：

dsh plugin --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": 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": ""
}

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

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

斜杠命令

决策阶梯

经验线（不是成功保证）：在没有额外失败证据时，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。

压缩失败三归因：
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{"能压缩吗？pressureTokens < window × 0.95"}
C -- 能 --> D["按阶梯给处方"]
C -- 不能 --> E["走交接 / 换大窗口模型"]
D --> F{"处方是动作？"}
F -- 是 --> G["复制 /compact 到剪贴板（或提示手输）"]
F -- 否 --> H["只给结论"]
G --> I["用户粘贴 /compact 执行，或触发交接"]

插件配置

未知键直接报错（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（provider/model）。只写型号会报错——同一型号在不同线路容量不同，按型号覆盖会把一条线路的实测值错用到另一条上，比不填更糟。
• 键可以直接用 context_pressure 返回的 routeKey，不用自己拼。
• 值取实测通过值的 ~80%，别贴着实测上限（手册 §1.2）；插件会取整。
• 有效窗口仍取 min(声明窗口, 实测值)：声明偏小时以声明为准，实测值不会把窗口放大。
• 值填错（0、负数、字符串、只写型号）在加载时就报错，不会静默生效。
• 没填的线路完全退回旧行为（标称值），所以升级不影响现有 profile。

> ⚠ 注意 DSH patch 的语义是同 id 整段替换 config，不是合并：在 profile 里覆盖 context-ops 这一行时，其它键也要一起写全，否则会打回默认值。

主动提醒（可选）

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

• 两档行为：
• pct ≥ remindAt（默认 85%）→ 建议压缩或交接；
• pct ≥ handoffAt（默认 92%）→ 暂停并请求确认：提醒模型展示五行 brief，并用 ask_user_question 请求用户确认；确认前不得写 CHECKPOINT.md，也不得宣称已自动交接。
• 确认闸不可绕过：主动提醒只是建议/暂停信号，不改变 context-handoff 的「用户确认后写盘」规则。
• 运行时上下文的持久化：提醒不伪造 user 消息，但宿主可能把 runtime-context 快照以去重后的 user/message 事件持久化；本插件只保证不通过 agent/pre-step 每轮重复追加，不承诺“绝不落历史”。
• 不伪造 user 消息：这是关键。走 agent/pre-step 往 decision.messages 里塞消息看着像「不落盘」，
  但宿主 step() 会把每一条非 runtime-context 的消息 session.append('user/message') ——
  提醒会进会话历史、出现在对话里、之后每个请求都重发，等于上下文插件自己给自己加压力。
• 只按档位变文案：文本里不带精确百分比和 token 数（那会让快照每轮重写）。跨档（85 → 95）才变；
  压力回落自动消失。
• 可忽略：文案带「可忽略」，不影响正常对话；要精确数字让它调 context_pressure。
• 默认关闭：enableReminder: true 才生效。

健壮性

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

本插件不写死 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 内置 test runner，无需额外依赖）
npm test

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

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

更新日志

见 CHANGELOG.md。

License

MIT © 廷宇