上下文女仆 Icstick/dsh-context-maid

dsh-context-maid

Awesome DSH Plugin

DeepSeek Harness (dsh) 的自动上下文策展插件——帮你把越来越臃肿的上下文收拾干净：优先清掉工具输出和无效日志，保护正在进行的工作和你在意的重点，压缩前先把值得留的存进记忆。

女仆的工作不是把房间一把火烧了，而是把垃圾扔掉、把重要的东西收进抽屉、把桌子擦干净——你随时能打开抽屉找回东西。

为什么需要它

长会话跑久了，上下文里堆满了没人再看的东西：一次失败的构建刷了几百行 stderr、同一个文件被读了五遍、某次实验的中间输出早被后来的结果取代。对话本身没多长，工具输出和无效日志才是占地方的大头。

与此同时，真正重要的东西——你半小时前说"这个必须用 pnpm"、当前进行到一半的目标、上一步刚确认的决策——夹在垃圾堆里，一旦触发压缩，可能连同垃圾一起被压成一段模糊的摘要。

dsh-context-maid 把这两件事分开处理：垃圾按垃圾清，重点按重点护。

一个小故事

你在调一个 FFT 工具的精度 bug，来回跑了十几轮。上下文里躺着：三次失败的调试输出（每次 300 行）、两份过时的频谱截图描述、五轮"再试一次"的中间结论……而真正的关键是——你中途说过"参考 ADI 的窗口函数实现，别自己发明"。

没有 maid：上下文到了阈值，一把梭压缩——你的关键要求可能被压成"用户提过窗口函数"。
有 maid：它先把过时工具输出清掉、把失败日志收走，你的原话被钉在不可压缩区，每次压缩前还会把它带进摘要指令："以下为用户明确要求，必须保留"。

核心能力

| 能力 | 说明 |
| 接管官方压缩 | MaidCompactionEngine 继承 BasicCompactionEngine 注册为 ctx.compaction（须 disable 官方 compaction-basic）；阈值经 trigger.userRatio 映射官方 thresholdRatio，官方 pressure/overflow/manual 三路触发全保留 |
| 压缩摘要增强 | 覆写官方 summarize：折叠前把高权威 PIN 事实注入摘要指令（软保护——官方压缩从头部压连续段，无法硬性排除中段）；注入消息用 source.kind: plugin:dsh-context-maid 标记生产者；摘要模型可配（便宜/本地/智能路由 resolver 链，回落官方） |
| tool 输出瘦身 | MaidSlimmer 继承官方 ToolResultPruner 注册为 ctx.toolResultPruner：错误留尾、JSON 留骨架、日志留头尾；eventSlim 落地即瘦身（M5：每次 step 前对新增超预算 tool 结果增量瘦身，默认开）+ 官方折叠压力路径全量瘦身 |
| 垃圾清扫（sweep） | sweeper 确定性识别（M6：真实事件模型 + surface 视角）——同工具同参数重复读取/失败后重试成功的前序结果 → model-free stub 整节点清理（无 LLM）；sweep.enabled 默认 false，开启后 step 边界节流清扫 |
| 先归档后压缩 | 折叠摘要经 ACP ledger 归档（agent_authored/single_observation/experience/private，sourceRef 含 compactionId）；归档为普通 observation，无 supersedes 链 |
| 阈值用户可调 + 迟滞 | trigger.userRatio 主旋钮（默认 0.40）映射官方 thresholdRatio；trigger.cooldownMs 防阈值抖动（C3）；slim.thresholdChars/headChars/tailChars 可调 |
| compact 模型可配 | 摘要可用便宜小模型/本地模型（OpenAI 兼容网关），也可接智能路由端点（registerSummarizationResolver） |
| 可观测 | 压缩（fold）/落地瘦身（slim）/垃圾清扫（sweep）写审计行，每行显式声明 unit（slim/sweep=chars，fold=estTokens）与 producer；C6 v1（2026-09-09）：压缩后对 PIN 事实做确定性锚点校验（op=pin，命中率 + 丢失锚点 + 不可校验事实数）；B12/B14（2026-09-21）：op=pin 同时报「可校验 V/F」与「命中 H/T」（只报命中率会把「没得验」算成「验过了没丢」），全丢时 warn；fold 行的 detail 带 foldDepth。折叠后约束校验（2026-09-25）：折叠前记「不可丢约束清单」摘要（PIN 集合 + 每条约束的 sha256 稳定标识 + 注入记账），折叠后给出三态结论 ok / partial / lost 并列出具体丢了哪些约束（lostIds），detail 增 status/checked/lostIds/manifestIds/injectedFacts/notInjectedFacts；被 PIN 预算截断、从未发给模型的事实单列，不再被算成「模型丢了」。/context-maid status 查引擎/瘦身器接线、配置、PIN 校验近 20 次分布、折叠后约束校验三态分布、本会话折叠深度与最近记录 |

折叠后约束校验的边界（未接线，勿夸大）：校验只比对摘要正文里的字面锚点，*不读折叠后的 session surface。不是省事——观测点在时序上不成立：官方 compaction-basic 先 append compaction/summary、其后才 append 带 surfaceOp: replace 的 checkpoint 消息（dsh-compaction-basic/lib/index.js:589 → :605），而 maid 的 summarize 钩子在两者之前被调用；此刻读 surface 拿到的是折叠前的节点，任何「约束仍在上下文里」的判定都会假绿。
也因此，校验结论默认只告警不阻塞：fold.verify.enabled=false 只关掉校验与留痕，不改写任何折叠行为；本仓也刻意不提供「校验失败即阻断折叠」的开关（软保护本就不可靠，把校验改成硬门，只会多出一处失败点）。

另一个口径事实：约束有两种下场——notInjectedFacts（我们自己没发出去：超 PIN 预算被整条截断）与 missed/lostIds（发出去了、摘要没带）。混在一起算，命中率会被系统性低估，排查方向也会从一开始就错。

智能体安装指南（面向自动化装配）

给需要在本机 dsh 装配本插件的智能体/脚本读；人工装配见下一节。
硬约束：① 必须 disable 官方 compaction-basic 与 tool-result-pruner（maid 接管同一 ctx.compaction 服务，官方不禁用则 maid 自动旁路不生效——防呆，见日志 warn）； ② pnpm install 前先停 dsh（Windows native DLL 锁）；③ 同 id patch 条目整体覆盖。

1. 定位 profile：<DSH_HOME>/profiles/<profile>/；先读 package.json，无 dsh.profile.bundles 键则 profile 未初始化，先初始化再继续。

2. 添加依赖（二选一）：

A. GitHub 源：CLI 自动把声明 dsh.bundle 的包加入 dsh.profile.bundles
dsh plugin --profile <profile> add github:Icstick/dsh-context-maid
B. 本地开发：profile package.json dependencies 加 "dsh-context-maid": "link:<绝对路径>", 并在同文件 dsh.profile.bundles 数组追加 "dsh-context-maid"

⚠️ dsh plugin add 不会写配置条目——第 3 步必须做。

3. 装配（profile 根 cordis.patch.yml，无则新建）：先 disable 两个官方引擎，再挂 maid：

- id: compaction-basic # 必须：官方默认引擎禁用，否则 maid 旁路 disabled: true
- id: tool-result-pruner # 必须：官方瘦身器禁用 disabled: true
- id: context-maid
name: dsh-context-maid
config:
auditDir: C:\path\to\context-maid # 建议显式（默认 $DSH_HOME/context-maid） 'trigger.userRatio': 0.4 # 可选：扁平点号键（schema 是扁平键，嵌套写法不生效）

4. 安装并重启：停 dsh → profile 目录 pnpm install → 重启 dsh。

5. 验证：对话里 /context-maid status 应输出 engine: ctx.compaction = MaidCompactionEngine（maid 提供，阈值映射生效）。

故障速查：status 显示 BasicCompactionEngine（官方）→ 官方没 disable，回去查第 3 步前两条；audit 目录落在意外位置 → auditDir 未显式配置；/context-maid 命令不存在 → commands 服务时序（插件会等待注册）或 bundle 未挂载。

安装与装配（重要）

GitHub 一键安装：dsh plugin --profile <name> add github:Icstick/dsh-context-maid 会挂载 context-maid 条目。装完必须按下方装配说明 disable 官方 compaction-basic / tool-result-pruner（maid 接管同一 ctx.compaction 服务，官方不禁用则 maid 自动旁路不生效）；auditDir 建议显式配置。

maid 接管官方引擎（继承 BasicCompactionEngine 注册为 ctx.compaction）与官方瘦身器（ctx.toolResultPruner）——cordis 同 key 服务只能有一个提供者，因此必须 disable 官方实例，否则 maid 自动进入旁路模式（防呆，见日志 warn）：

profile cordis.patch.yml（如 web profile）
- id: compaction-basic
disabled: true
- id: tool-result-pruner
disabled: true

然后在 profile package.json 加依赖并 insert maid：

{ "dependencies": { "dsh-context-maid": "link:D:/path/to/dsh-context-maid" },
"dsh": { "profile": { "bundles": ["dsh-context-maid"] } } }

同一 cordis.patch.yml
- insert:
- id: context-maid
name: dsh-context-maid

重启后 /context-maid status 应显示 ctx.compaction = MaidCompactionEngine（maid 提供）。

配置（用户可调）

| 键 | 默认 | 说明 |
| trigger.userRatio | 0.4 | 主旋钮：上下文阈值（占模型窗口比例）。映射官方 thresholdRatio，0.05-0.95 |
| trigger.cooldownMs | 0 | 压缩迟滞（C3，2026-10-05）：0 = 关（默认，行为与改动前逐字一致）；设为毫秒值后，距上次成功压缩不足该时长的 pressure 触发会被静默跳过。context-overflow 永远豁免（硬约束，跳过会把 turn 撑崩）。本机用 300000（5 分钟） |
| trigger.eventSlim | true | 落地即瘦身（M5）：step 边界对新增超预算 tool 结果增量瘦身；关掉 = 仅官方折叠压力路径内瘦身 |
| slim.thresholdChars | 4000 | tool 输出超过即内容感知瘦身（eventSlim 与官方折叠压力路径） |
| slim.headChars / tailChars | 800 / 800 | 瘦身保留预算 |
| sweep.enabled / aggressive | false / false | 垃圾清扫（M6）：开启后按 step 边界节流，识别并 stub 结构性垃圾（aggressive 档规则未扩展，保留开关） |
| fold.retainRatio | 0.16 | 压缩保留尾比例 |
| fold.verify.enabled | true | 折叠后约束校验（2026-09-25）：折叠前记录「不可丢约束清单」摘要（PIN 集合 + sha256 稳定标识 + 注入记账），折叠后校验约束是否仍可用，ok/partial/lost 写入审计 op=pin。默认只告警不阻塞；置 false = 不校验、不留痕，折叠行为不变 |
| pin.enabled / extra | true / [] | 钉扎软保护：折叠摘要注入高权威事实（M3）；逐轮注入由 ACP Composer 单轨承担（pin.inject 已删 0.3.0） |
| archive.enabled | true | 先归档后压缩（需 ACP） |
| summarization.provider / model | '' / '' | 摘要模型可配（空=跟随对话模型；可填便宜模型或本地 OpenAI 兼容网关） |
| auditDir | $DSH_HOME/context-maid | 审计库位置 |

设计文档

完整设计（五级策展模型、模块架构、配置全表、M1-M4 里程碑、测试计划）见 docs/design.md。

仓库级开发计划与问题登记（backlog）：docs/DEVELOPMENT-PLAN.md。

开发

node --test "test/.test.mjs"

License

MIT License。