dsh-compactor
DeepSeek Harness 的 Context Compaction 插件：工具结果裁剪、使用 LLM 或离线规则进行摘要并提供面向用户的压缩报告、防死循环保护，以及通过 /restore 回滚。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:lionwill/dsh-compactor#64e5c5877a363d883f38b274c5f3e7deca07c9d1Compactor 以 dsh-compactor 发布，当前版本为 0.4.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
语言 / Language：中文（GitHub 默认展示） ｜ English
DeepSeek Harness（dsh）的上下文压缩（Context Compaction）插件。 cordis4 原生（ESM），面向 dsh 0.1.2-alpha.3+。
长会话中，模型的输入由全部历史消息组成：用户问题、助手回复、工具调用与工具原始结果。工具结果（搜索结果、文件内容、命令输出）往往占上下文的绝大部分，且大部分细节对后续推理无价值；此外重复的工具调用与"车轱辘话"式回复会持续膨胀上下文并诱发循环。
本插件在不破坏 dsh append-only 会话日志的前提下做三层处理：
tool/result）进入事件流时按固定策略剪枝（搜索只留标题/链接/短摘要，文件只留预览，命令输出只留退出码与关键行）。/restore 可随时完整还原。另有死循环护栏：观测 tool/call 事件流，同一工具以相同参数被调用 ≥3 次注入 anti-loop 提醒上下文，≥5 次记入取消判定（cancelledCount）并留下取消说明，供宿主 toolRuntime 消费。
| 引擎 | 触发 | 依赖 | 说明 |
|---|---|---|---|
| API 摘要 | 自动阈值 / ctx.compactor.compactSession() | DEEPSEEK_API_KEY | 调用 deepseek-chat（temperature 0.1）做骨架化摘要；无 Key 时自动降级为本地抽取式兜底 |
| 本地规则压缩 | /local-compact 命令 / ctx.compactor.localCompactSession() | 无（零网络、零新增依赖） | 固定规则 + 正则：重复句折叠、搜索留 top-K、文件留头尾行、命令只留错误行、调试尝试合并、摘要长度硬上限。需用户确认一次后执行 |
两种压缩完成后都会向用户输出结构化结果告知：逐条列出压缩范围（如"工具原始结果（web_search ×2，原文约 4600 字符）"）、每处与整体的压缩比、before→after token、预计下次请求少发的输入 token、关键信息保留率是否达标，并提示可用 /restore 回退。自动压缩的结果同样写入 dsh 日志（ctx.logger.info）。
session/event（按 tool/result / assistant/message / tool/call 分派）、服务注入 static inject = ['sessions', 'commands']、配置 schema 用 @deepseek-ai/schemastery、定时扫描由 ctx.effect 托管生命周期。/compact 不重复注册（dsh 0.1.2-alpha.3 内置 @deepseek-ai/dsh-command-compact）；本插件提供 /local-compact 与 /restore。
⚠️ 纯
dsh-web-appprofile 默认在 host 平面禁用command-compact（disabled: true），打斜杠看不到/compact。本插件的 bundle patch 会显式重新启用compaction-basic、command-compact、tool-result-pruner（在 web-app 之后应用），因此装了这个插件后/compact与/local-compact都能调出。
ctx.compactor：project() / compactSession() / localCompactSession() / restore() / prune()。| 命令 | 作用 |
|---|---|
/local-compact | 首次调用只输出风险说明与确认方式，不压缩 |
/local-compact confirm | 用户确认后执行本地规则压缩并输出压缩报告（confirm/yes/确认 均可） |
/restore | 从归档恢复上一次压缩前的原文（API 与本地压缩均可回退） |
# 从 GitHub（pnpm 会执行 prepare 自动编译）
dsh plugin add "github:<owner>/dsh-compactor#v0.4.1"
# 本地开发
dsh plugin add "dsh-compactor@file:/path/to/dsh-compactor"
⚠️ 本插件是 dsh bundle：
package.json声明了dsh.bundle.patch（指向cordis.patch.yml）。 dsh 0.1.2-alpha.3+ 只激活声明了dsh.bundle的包为 profile 层；安装后它会自动加入dsh.profile.bundles并生效。若dsh plugin打印 "declares no dsh.bundle" 警告， 说明装的是旧版（缺少该字段），请升级到本版本。
cordis.patch.yml（dsh bundle patch，YAML 数组，插件包内置已正确配置；用户如需覆盖按 id 覆盖即可）：
- insert:
- id: dsh-compactor
name: dsh-compactor
config:
thresholdTokens: 32768 # 触发压缩的 token 阈值
targetTokens: 8192 # 压缩目标 token 数（参考值）
compressInterval: 300 # 定时扫描间隔（秒）
retainRecentRounds: 3 # 最近 N 条消息永不压缩
summaryModel: deepseek-chat
enablePruning: true # 实时层剪枝
enableSummary: true # API 摘要（无 Key 时自动降级本地兜底）
exemptTools: [write, edit, task] # 豁免工具（剪枝/护栏/本地压缩均跳过）
qualityThreshold: 0.85 # 关键信息保留率告警阈值
# localRulesPath: /path/to/my-rules.json # 可选：本地规则文件路径
API 摘要需要密钥：export DEEPSEEK_API_KEY=sk-...（不设置则 API 路径自动使用本地抽取式兜底）。
/local-compact 规则文件（local-rules.json）规则/正则全部集中在包根 local-rules.json，加载优先级（深合并，后者覆盖前者）：
内置默认 ← 包根 local-rules.json ← 环境变量 DSH_COMPACTOR_RULES=<路径> ← 配置 localRulesPath（显式路径读取失败会报错）。
{
"maxSummaryChars": 1200, // 本地摘要硬上限（超出截断并标注）
"maxKeptSentences": 8, // 长回复最多保留句数（先去重再截断）
"userLineMaxChars": 200, // 用户问题行保留上限（骨架优先保留）
"callArgsMaxChars": 80, // 工具调用参数行截断
"fallback": { "headChars": 300, "tailChars": 160 },
"toolRules": {
"web_search": { "keepTopResults": 5, "relevanceField": "relevance_score", "titleField": "title", "urlField": "url", "linkField": "link", "dropFields": ["snippet", "description"] },
"read_file": { "headLines": 20, "tailLines": 5 },
"code_execution": { "maxStdoutLines": 30, "maxStderrLines": 10, "errorPattern": "error|exception|failed|traceback|panic|错误|失败|异常|报错" }
},
"patternRules": {
"research_chain": { "mergeUrls": true, "maxMergedUrls": 8 },
"code_debug": { "attemptPattern": "第\\s*\\d+\\s*次|attempt\\s+\\d+|retry|重试|再次", "keepLast": true }
}
}
/local-compact 为测试与开发中的规则实现，质量通常低于 API 摘要。qualityThreshold 时报告会给出 ⚠️ 明示；此时建议核对或直接 /restore。/local-compact 第一次执行只会要求确认、不会动数据；确认后如不满意，立即执行 /restore 可完整还原原文。/restore 只能恢复本插件（API 压缩与 /local-compact）产生的压缩；dsh 内置 /compact 的回退由 dsh 自身语义决定。$DSH_DATA_DIR/archive/（无该变量时为 ./.dsh-compactor-archive/）；请确保目录可写，且不要手工编辑归档文件（append-only）。exemptTools 中的工具（默认 write/edit/task）不会被剪枝、护栏和本地压缩触碰；如工作流依赖其结果，请勿移除。/local-compact 都会重新读取。/compact，与 dsh 内置压缩命令互不冲突；两者可并存。dsh-compactor/
├── package.json # npm 包定义（ESM；cordis/schemastery 为 peerDependencies，由 dsh 宿主提供）
├── tsconfig.json # NodeNext ESM 编译配置（prepare 钩子自动构建）
├── local-rules.json # /local-compact 规则与正则配置（独立文件，可覆盖）
├── cordis.patch.yml # 插件配置样例（合并进 dsh 配置）
├── LICENSE / README.md / README.en.md # 许可与文档（中文默认展示，英文版见 README.en.md）
└── src/
├── index.ts # Compactor Service：事件接线、压缩管线、定时扫描、护栏、结果上报
├── config.ts # schemastery 配置 schema 与默认值
├── report.ts # 压缩结果报告（压缩范围/压缩比/预计节省/保留率/结论文案）
├── adapter.ts # dsh Session（surface.nodes + events）↔ 扁平消息投影
├── estimator.ts # token 估算（CJK-aware 启发式，可注入真实 tokenizer）
├── segmenter.ts # 可压缩片段识别与 tool-call↔tool-result 边界对齐、连续块合并
├── pruner.ts # 实时层工具结果剪枝策略（web_search/read_file/code_execution/默认）
├── summarizer.ts # API 摘要调用（可注入 transport）+ 本地抽取式兜底
├── local.ts # /local-compact 本地规则引擎（确定性、零网络）+ 规则文件加载
├── patterns.ts # 片段模式识别（research_chain/code_debug/normal_conversation）
├── store.ts # append-only 原文归档（JSONL，/restore 数据源）
├── monitor.ts # 压缩事件监控与关键词保留率统计
├── guard.ts # 死循环护栏（同参计数：≥3 提醒 / ≥5 取消判定）
├── commands.ts # /restore 与 /local-compact（两步确认）注册
├── events.ts # cordis4 事件类型声明
└── types.ts # 共享类型