English

dsh-context-triage

会话上下文分诊插件，为 DeepSeek Harness（dsh）自动管理长会话的上下文体积：识别并处理过期、重复、失败、超大与低价值的消息内容，节约 token 预算，缓解上下文膨胀。

特性

• 确定性、零模型依赖：全部判定与改写由启发式规则完成，不调用 LLM、不需要额外服务，行为可预测、可离线测试。
• 五种筛查器（Screeners），各自独立可开关： | 筛查器 | 判定规则 | 处理动作 | | --- | --- | --- | | 过期输出 staleOutput | 距最近用户消息超过 N 轮、且结果仍完整的工具调用对 | 调用块改写为归档摘要，结果块移除 | | 重复调用 repeatedCall | 同工具、同参数（JSON 键序无关）的调用对 | 仅保留最近一次，旧调用对被切除 | | 失败调用 failedCall | 过期的错误结果（isError） | 输入参数替换为失败桩（防泄露/省体积），错误文本保留并裁剪 | | 超长块 oversizedBlock | 工具结果文本超过字符上限 | 头尾裁剪，中间标注省略量 | | 过期思考 staleReasoning | 超过保留轮次的 reasoning 块；保留的块超出长度上限 | 移除；或裁剪（保留区内只剪不删） |
• 保留区（reserve）：最近 N 个用户轮次内的内容一概不动，避免破坏模型正在使用的上下文。
• 豁免清单（exempt）：工具名与文件路径 glob 双维度豁免（默认保护 task/skill/todowrite/todoread/write/edit/batch 等有状态工具）。
• "值得"检查：任何归档/桩化动作都要求改写后严格小于原文，杜绝越改越贵；调用对级别的动作（归档 = 改写 + 切除）以原子组方式整体生效或整体放弃。
• 审计报告：每次分诊输出结构化统计——按原因汇总的条数与节省量、逐条明细、建议压缩区间；通过工具、命令与 CLI 三处可见。
• 原生接入 dsh 压缩接缝：实现 ctx.compaction（CompactionEngine），自动压力、上下文溢出、手动与强制区间压缩四条路径全部走 harness 官方机制，替换型摘要消息使用 checkpoint 来源，任何后端无关的消费者都能识别。

安装与挂载

插件以 bundle 形态分发：package.json 的 dsh.bundle.patch 指向 cordis.patch.yml（补丁内容为插入插件行，配置项可整行覆盖）。

在 DSH 中安装

dsh plugin --profile demo add github:JohnXu22786/context-pruner

方式一（本地目录挂载，推荐）：

dsh plugin --profile web add link:/绝对路径/context-pruner

方式二（手动补丁）：把 cordis.patch.yml 中的条目合并进 profile 的 cordis.patch.yml，或直接作为 overlay 启动：

dsh web --patch ./cordis.patch.yml

方式三（git 源）：

dsh plugin --profile web add "github:你的仓库/context-pruner#main"

挂载后可用 dsh --profile web --dump-config 检查插件行是否进入启动树。

注意：ctx.compaction 同一上下文只能有一个提供者。若你的 profile 已加载其他压缩实现（如自带的基础压缩后端），请通过补丁 disabled: true 关掉其一，二者不能共存。

接口

入口（manifest）

| 项 | 值 | | --- | --- | | 包名 | dsh-context-triage（package.json 的 dsh.bundle.patch 声明 bundle） | | 主入口 | lib/index.js（main/exports；另有 ./core 与 ./dsh 子路径供嵌入方使用） | | 插件名 | context-triage | | 依赖注入 | tools（必需）；命令注册表通过 ctx.get('commands') 可选探测，无则静默跳过 | | 配置 | 导出 Config（Schemastery Schema），默认值见下文配置表 |

插件形态为函数式插件：导出 name / inject / Config / apply(ctx, config)，由 cordis 校验配置并填充默认值后调用。

提供的扩展点

| 扩展点 | 说明 | | --- | --- | | 服务 ctx.compaction | TriageCompactionEngine extends CompactionEngine，实现 compactIfNeeded（自动压力 / 溢出）、compactNow（手动空闲压缩）、compactRegion（强制区间压缩） | | 工具 triage_history | 模型可见；参数 dryRun?: boolean。执行一次分诊并把审计报告返回给模型；dryRun=false 且存在值得处理的区间时直接应用 | | 命令 /triage | 人类命令，不经过模型；输出审计报告并应用值得的处理 |

压缩事务如何落地

分诊结果以标准压缩事务写入会话日志（append-only，不改写历史）：

1. compaction/start（持锁，直到配对的 compaction/end）
2. compaction/summary（摘要内容、被遮蔽区间、遮蔽 seq 清单与启发式 token 代价；llmStreamCall 缺省 = 非模型摘要）
3. user/message + surfaceOp: { op: 'replace', start, end } + sourceEventSeqs（替换型摘要消息，source 为 checkpoint 来源）
4. compaction/end

模型可见历史由会话日志派生，替换发生后 deriveMessages() 自然产出 [摘要消息, ...保留内容]——无需任何对历史记录的原地修改。

配置

全部字段有默认值，仅需覆盖想调整的部分；非法值（负轮次、比率越界等）在加载期直接抛错。示例：

# cordis.patch.yml
- insert:
    id: context-triage
    name: dsh-context-triage
    config:
      budget:
        contextTokens: 200000   # 小上下文模型按需调低
        softRatio: 0.6
      screeners:
        staleOutput: { turns: 5 }
        staleReasoning: { enabled: false }
      exempt:
        tools: [task, skill, write, edit]

| 字段 | 默认值 | 说明 | | --- | --- | --- | | enabled | true | 总开关 | | reserve.turns | 3 | 保留区：最近 N 个用户轮次内的内容不接受任何处理 | | budget.contextTokens | 1000000 | 预估上下文窗口（token），决定压力比率 | | budget.softRatio | 0.7 | 使用率超过该比例 → 自动压缩触发（pressure） | | budget.hardRatio | 0.9 | 使用率超过该比例 → 压力报告标记为强制（hard）等级 | | budget.minSavingsTokens | 2000 | 预估节省低于该值不做任何动作 | | screeners.staleOutput.turns | 8 | 距最近用户消息超过 N 轮的调用对归档 | | screeners.repeatedCall.enabled | true | 重复调用切除 | | screeners.failedCall.turns | 4 | 失败调用处理阈值（轮） | | screeners.failedCall.errorKeepChars | 400 | 失败调用保留的错误文本上限（字符） | | screeners.oversizedBlock.capChars | 6000 | 工具结果文本上限（字符），超出则头尾裁剪 | | screeners.oversizedBlock.headChars / tailChars | 800 / 400 | 裁剪保留的头部/尾部长度 | | screeners.staleReasoning.keepTurns | 3 | 保留最近 N 轮用户消息内的思考块 | | screeners.staleReasoning.maxBlockChars | 2000 | 保留思考块的长度上限，超出裁剪 | | exempt.tools | [task, skill, todowrite, todoread, write, edit, batch] | 豁免工具名 | | exempt.filePatterns | [] | 豁免路径 glob（匹配调用参数 filePath/path），如 ['**/*.lock'] | | summary.capChars | 20000 | 压缩摘要字符上限 | | summary.headRatio | 0.4 | 摘要裁剪时的头部保留比例 |

本地体验（无需 dsh）

src/core 是框架无关的引擎，附离线回放 CLI，可直接对一份 JSONL 会话文件运行：

npm install
npm run build
node lib/cli/replay.js examples/session.sample.jsonl --config examples/demo.config.json
node lib/cli/replay.js examples/session.sample.jsonl --config examples/demo.config.json --show-transcript

回放格式（每行一个 JSON 事件，seq 由行序决定）：

{"type":"user/message","text":"项目构建失败了"}
{"type":"assistant/message","reasoning":"…","calls":[{"id":"c1","name":"bash","arguments":"{\"cmd\":\"npm run build\"}"}]}
{"type":"tool/result","callId":"c1","text":"…","isError":false}

示例输出见 examples/report.example.md；测试覆盖全部筛查器、合并优先级、原子组、审计一致性与端到端回放（npm test）。

设计取舍

• token 估算是启发式：CJK 约 1 token/字、其余约 4 字符/token，仅用于压力判断与审计统计，不参与计费。窗口大小请按实际模型配置 budget.contextTokens。
• 改写必有净节省：归档摘要、失败桩、裁剪三者都在动作前比较改写前后规模，不划算的发现被自动放弃；调用对动作以原子组整体判定，不会出现"摘要留下、结果被拆"的半吊子状态。
• 提示缓存：压缩会改变消息序列，使该点之后的提示缓存前缀失效。长会话中节省的 token 通常远大于缓存重算成本；对按请求计费的提供商（无缓存计费）则只有收益。
• 不碰用户输入：超长块筛查只作用于工具结果；用户消息除非被整体保留区覆盖，否则永不被改写。

许可

本项目基于 MIT 许可开源。