上下文压缩器 ScreamingMaggot/rcs-context

StateCompiler（RCS）— DSH 插件包 / 直装包

dshfind

把长对话的重复计费砍掉一半，再给模型配一名只读调查员：先核实，后动手。

把 EXTREASON（reasoning 外置）+ CONTEXTinjector（注入折叠）+ LOGcompiler（转录日志）+ contextinjector-webui（「注入」面板） 一起装进 DeepSeek Harness（DSH）的 web profile。
装好后在会话侧边找到「注入」tab 使用。自 0.1.25 起，本仓库同时是可被 dsh plugin add 直接安装的插件包 （仓库根有 package.json 声明 dsh.bundle，随包自带补丁层）。

本包版本 / 来源提交 / 构建时间见同目录 version.json；本版改动与保留项见 RCS-0.1.27-改进与保留项.txt（历史各版同目录）。

兼容性（dshTarget: 0.2.0-rc.2）：插件含多代兼容层——同一份文件同时适配 0.1.5-rc.2 / 0.1.7-rc.2 / 0.2.0-rc.2 三代宿主接口（消息来源标记 / 事件枚举 / 子代理接口 / 工具结果形状四族差异均为双形态实现）。对 0.2.0-rc.2 的核验：14 个关键宿主包中 10 个逐字节相同（含 dsh-session-format、dsh-session-projection、dsh-tool-subagent），插件侧依赖的 16 条接缝 0 条消失、0 条改名，宿主装载与真实会话使用均已验证。安装方式见下节：包安装（dsh plugin add，0.1.25 起支持）或 install.ps1（离线 / 无 pnpm 环境）。
已验证：0.1.7-rc.2（session-format v4 全链路，含折叠提交与审计）。
- 折叠的内容完整性由提交前守卫保证：其中一条专门比对"被折叠的工具结果数 ↔ 转录里留下的工具记录数"，少一行就整次拒绝、本轮按原文发送（0.1.23 起；动机见 RCS-0.1.23-改进与保留项.txt）。
注意：新宿主的 dsh_plugin_packages 请求扩展与『改写历史』的折叠互斥，折叠档位需按 RCS-0.1.21-改进与保留项.txt 的 09-27 补录在 profile 层关闭该扩展（安装脚本已处理）。

目录

├── web/ 插件本体（进 profiles/web/） │ ├── contextinjector.mjs 注入折叠插件 │ ├── logcompiler.mjs 转录日志插件 │ └── extreason.mjs 外置推理插件（EXTREASON） ├── condense/chunk.mjs,ivr.mjs 共享纯模块（转录分型 / 压缩器 IO 比） ├── toolfold/toolfold.mjs 工具结果折叠（被上面两个 import） ├── contextinjector-webui/ WebUI 面板 npm 包（host /api + client 注入） ├── package.json 包清单（声明 dsh.bundle） ├── cordis.patch.yml 包自带补丁层（四条 insert） ├── install.ps1 / install.cmd 直装（web profile） ├── uninstall.ps1 卸载/回滚 ├── tests/ 回归测试（漂移 #11 覆盖 / toolfold 单行契约） ├── README.md 本说明 ├── LICENSE.txt MIT 开源许可证 ├── version.json 产物来源/版本/提交/构建时间 └── RCS-0.1.-改进与保留项.txt 各版改动、保留项、读数纪律

目录分成 web/ + condense/ + toolfold/ 不是随手排的：插件源码里写的是 ../condense/chunk.mjs、 ../toolfold/toolfold.mjs，而这个布局与装进 DSH_HOME/profiles/ 后的布局同构，于是"包安装"与"脚本安装"两条路共用同一份源码，不需要任何分叉。

从零安装（终端，适用于 GitHub 克隆）

方式一：作为插件包安装（0.1.25 起，推荐）

dsh plugin --profile web add github:ScreamingMaggot/rcs-context
然后把它选进该 profile 的层列表（dsh plugin add 不会自动激活 bundle）：编辑 <DSH_HOME>/profiles/web/package.json，把 "rcs-context" 加进 dsh.profile.bundles 最后重启 dsh web

装成功并激活后，启动日志里应出现四条装载行（[CONTEXTinjector] armed … / [logcompiler] v3 …
/ [EXTREASON] armed … / [contextinjector-webui] … ready）。没有这四行 = 层没被选中。

方式二：install.ps1 直装（离线 / 无 pnpm 环境）

git clone https://github.com/ScreamingMaggot/rcs-context.git
cd rcs-context
powershell -ExecutionPolicy Bypass -File ./install.ps1
需指定目标时：-DSH_HOME <配置家目录> -DshInstall <dsh 安装根>

安装脚本会：备份现网 → 落位插件与 WebUI 包 → 幂等追加 profile 补丁（四项挂载 + 一条按宿主探测的兼容项）→ 自校验。重复运行安全。
平台说明：插件本体为跨平台 .mjs（随宿主运行）；安装/卸载脚本目前仅提供 Windows PowerShell 版本。

一键直装（Windows）

在已运行/即将运行的 DSH 所在机器上，双击 install.cmd，或： powershell -ExecutionPolicy Bypass -File .\install.ps1 默认装到 %DSH_HOME% 或 ~\.dsh 的 web profile；可显式指定： .\install.ps1 -DSH_HOME "D:\path\to\.dsh" -DshInstall "D:\path\to\dsh-runtime" 脚本会：备份现网 → 落位插件与 WebUI 包 → 幂等追加 cordis.patch.yml 四项 insert → 自校验。重复运行安全。

装完必做

1. 重启 dsh web（client 装载器按名缓存，必须重启才生效；刷新页面不够）。
2. 打开一个会话 → 「注入」tab：
- CONTEXTinjector（默认关）：右栏「当前会话」卡为本会话选「工具折叠 / 单压缩 / 双压缩」即启用折叠；
- 工具折叠=对每轮对话做工具转录折叠（保留原始信息）
- 单压缩=对每轮AI输出进行语义压缩
- 双压缩=单次压缩基础上进行关键值保真提取
- LOGcompiler（默认全会话记录）：日志写到 $DSH_HOME/state-compiler/transcripts/<sid>.log；在「日志编译」区可改输出目录/停用/逐会话开关。
3. 压缩通道（single/double 的浓缩调用）默认跟随会话模型——不建议：那会按主模型价格计费。
请按下方『成本提示』把浓缩指向本地 Ollama 或任一廉价模型；压缩失败会无损回退，不会破坏档案。
4. EXTREASON（外置推理，默认开）：主模型 reasoningEffort: off（或模型无思维链能力）时，每轮自动跑一个只读子代理（UI 里显示为「外部思考中」）并把它的 [R] 行注入当轮请求。
不需要时设环境变量 EXTREASON=0。详见 EXTREASON/README.md。

界面截图（实拍）

①「注入」面板：左上为压缩比走势（蓝线=每轮、绿线=累计，虚线=比值 1 参考线），中间是本次折叠读数（8951 → 725 B、8%、档位 double、单调性 ✓）与请求结构逐段字节，右侧是当前会话的档位与开关。

注入面板

② 会话输入区的档位选择器（默认「关」；开启折叠后每一轮的下方即出现压缩读数）：

档位选择器

③「外部思考中」：主模型少想快跑的同时，只读调查员在当轮实际执行 分析 / 搜索代码 / 读取文件：

外部思考

④ 调查员简报（[R] 行）：逐行标明文件与行号、指出唯一实质性不一致点并给出两个可选动作，末尾声明「只做了只读检查、未运行、未改动任何文件」：

R 简报

⑤ 折叠进行中：会话标签旁显示「压缩中」，面板给出触发点（TURN-END）、耗时与本轮读数（775 → 179 B、23%、档位 single、单调性 ✓）：

折叠进行中

截图取自真实长会话，未做美化。

成本提示（重要）：压缩通道请走本地或廉价模型

为什么：single / double 档位会为每条被折叠的助手输出调用一次"压缩模型"（实测每局中位 20 / 42 次）。
若这条通道走主模型，等于用主模型的价格反复付压缩费——省钱的效果会被吃掉大半。
把压缩模型换成本地 Ollama 或任一低价模型，这部分开销接近于零，而无损折叠的收益一分不少（收益主要来自工具结果折叠，它不需要模型）。

怎么配（两步）

① 在 DSH 的 ~/.dsh/settings.yaml 注册本地 Ollama（三个字段缺一不可，都是实测踩出来的）：

llm-pi-ai:
providers:
ollama:
displayName: Ollama (本地) api: openai-completions baseURL: http://127.0.0.1:11434/v1 apiKeyEnv: OLLAMA_API_KEY # 本地服务任意值即可，但字段必须在 compat: maxTokensField: max_tokens # 关键：ollama 只认 max_tokens，缺此字段输出上限失效 streamIdleTimeoutMs: 30000 # 卡住 30s 即无损回退，不拖垮整轮 models:
- id: qwen3:4b-instruct-2507-q4_K_M
name: Qwen3 4B (本地压缩器) reasoningEfforts: off: null medium: medium # 显式声明：不写会被判为"不支持任何思考档"

② 把压缩通道指过去（三选一，优先级从高到低）：
- WebUI「注入」面板里为该会话选择压缩模型（最直观）；
- 会话的 control.json 写 {"condenseProvider":"ollama","condenseModel":"qwen3:4b-instruct-2507-q4_K_M"}；
- 环境变量 DSH_CONTEXTINJECTOR_CONDENSE_PROVIDER / DSH_CONTEXTINJECTOR_CONDENSE_MODEL。

用弱模型的代价：压缩率会低一些、单次更慢（4B 级一条约 7–15s），但不会出错——压缩超预算或质量不达标时插件一律无损回退（原文照旧进转录），档案与可回放性不受影响。

EXTREASON 不需要单独配：它的子调查员每轮调用一次模型，但简报会让主模型少读历史——实测计费中位反而更低（11.2 万 vs 不开的 14.0 万），故无需为它指定廉价模型。

权限边界与第三方网络依赖（如实声明）

- 写入范围：仅 $DSH_HOME（web profile 目录、state-compiler 状态目录、转录日志、按需创建的 raw/ 归档与折叠审计 fold-index/）。不写系统目录、不改 PATH、不改 shell 配置。
- 进程形态：作为宿主进程内插件加载，不安装后台服务、不注册开机项。
- 插件自身不发起任何网络请求。仅两处例外，且都必须由你显式配置后才发生：
1. 把压缩通道指向本地/远程 Ollama（或任一 OpenAI 兼容端点）时，该请求由宿主的 LLM 适配器发出；
2. EXTREASON 的子调查员使用宿主已注册的模型与只读检索工具（若启用了网页检索，则走宿主自身的检索通道）。
- 子会话权限：EXTREASON 的子会话以只读工具集运行（读文件 / 检索），不具备写权限；产出以 [R] 行注入。
- 凭据：插件不读取、不存储模型凭据（由宿主凭据服务管理）。
- 卸载：uninstall.ps1 回滚补丁项与文件（含安装时备份的还原）。

卸载

.\uninstall.ps1 # 还原安装前备份 / 移除补丁项与文件删干净后再重启 web。

A档实验：工具结果结构化折叠（0.2.0 起，默认关）

实验功能，默认 OFF，不影响既有行为。开启后，折叠历史里的工具结果会从 [T] tool|path|OK
升级为结构化短行 [T] <域>|<action>|<target>|OK|P0–P3|<k=v>… 并追加值保真链 [V]：
read 保留 size/sha8/lines、edit/write 失败把 err 原文入 [V]、glob/grep 留 pattern/count/matches≤K、 bash 留 head/tail/tee、ask_user 答复 P3 逐字入 [V]（不可重建）。
开启方法：装好后在会话「注入」tab → 右栏「当前会话」卡 → 先为本会话选一个压缩档（工具折叠/单压缩/双压缩，让它进入折叠），再打开下方 「工具结果结构化折叠（实验）」 开关。
纯规则、无 LLM；有 token 成本，仅在你开启的会话生效。若内测发现问题，把现象/转录反馈即可。

说明 / 数据位置

- 运行时配置与控制：$DSH_HOME/state-compiler/（control.json、logcompiler.control.json、last-fold.json、transcripts/、.ctxinjector/raw/）。
- 安装备份：$DSH_HOME/.statecompiler-backup-<时间戳>/（uninstall 用它回滚）。
- 源码与重建：见 StateCompiler 仓库 build-dist.ps1（从 git HEAD 可复现本目录；该脚本自带 pre/post-flight：校验发布脚本 BOM、校验 version.json 版本号、对每个 .mjs 跑 node --check）。

发布前自检（仓库侧，可随时复跑）

powershell -ExecutionPolicy Bypass -File StateCompiler\packaging\smoke-install.ps1
它在 %TEMP% 造一个假 DSH_HOME 真跑一遍 安装 → 重复安装（幂等）→ 半装升级 → 卸载回滚，并核对本目录自洽（清单齐全、version.json 可解析且版本一致、.ps1 带 BOM、.mjs 不带 BOM、发布说明是合法 UTF-8 中文、装出来的插件与 dist 逐字节一致）。全绿才发。

运行参数（control.json，多数热读、免重启）

| 键 | 缺省 | 作用 |
| enabled | true | 总开关 |
| sessions / sessionModes | [] / {} | 白名单会话及其压缩档（off/single/double/工具折叠）。未列出的会话不折叠（无全局默认档） |
| keepInject | ON | DSH 注入节点（runtime/policy 快照、skill 目录）永不被遮蔽 ⇒ 快照零补发 |
| toolfoldStructured | true | 工具结果结构化 [T]/[V] |
| condenseProvider / condenseModel | 跟随会话 | 指定浓缩模型（如本地 ollama） |
| condenseMinBytes | 240 | 单条 [A] 低于此字节不送浓缩（0 = 全送，注意小值会让折叠变慢：实测 15 曾导致 243s 一次折叠） |
| condenseMaxTokens | 700 | 单条浓缩输出上限 |
| condenseBudgetMs / condenseMaxCallsPerFold | 15000 / 12 | 一次折叠的硬预算（时间长/调用多即止损回退） |
| foldJoinTimeoutMs | 3000 | 下一轮发请求前等待后台折叠的上限；超时就先发请求，绝不拖住对话 |
| segments | OFF | 多段转录（head 独立成段零重复 + 各段独立留面）。真机已验证，默认关；开启前建议按 NOTES 的样本门槛评估 |
| standalone | OFF | 遗留开关（新段不带旧前缀）。其目的已被多段转录覆盖，暂不推荐单开 |

装好后怎么自查（不看日志也能判）

- 面板：会话「注入」tab 显示最近一次折叠（模式/触发/字节/压缩比/monotonic）、面板「压缩中」在飞标记。
- 端点：GET /api/context-inject/status（含 lastFold、foldInflight、control、sessions）。
- 文件（都在 $DSH_HOME/state-compiler/）：
- .ctxinjector/fold-index/<sid>.jsonl —— 每次折叠一行：cumLines.before/after 应相邻承接、after 等于转录行数；
- .ctxinjector/fold-errors/<sid>.jsonl —— 拒折/异常账本（空 = 健康）；出现持续 foldtext-drift 表示表面转录与状态脱节、折叠会停摆；
- last-fold.json —— 最近一次折叠详情（含 full 转录全文、segments、afterNodes）。
- 一键体检（仓库侧，任意机器只读运行）：
node StateCompiler\CONTEXTinjector\tools\verify-fold-integrity.mjs --state <DSH_HOME>\state-compiler --all

逐会话输出 PASS/WARN/FAIL：索引承接、full 段头链、拒折账本；可选 --replay 追加「表面段拼接 == full」校验。

什么时候开 single / double（实证口径，2026-09-12）

用 12 个真实工作场景 × 4 档（bare 基线 / off 无损工具折叠 / single / double）实测的结果：

| 档 | 机制级压缩率（字节加权） | 峰值上下文比（中位） | 峰值 ≥18K 时 |
| off（工具折叠） | 0.227（压到约 1/4） | 0.931× | 0.717× |
| single | 0.209 | 1.049× | 0.843× |
| double | 0.210 | 0.991× | 0.742× |

- 无损工具折叠（off）在任何规模都稳赚，且不调用任何模型（零 token、零延迟），是默认推荐档。
- LLM 浓缩（single/double）只在长会话转正：峰值 ≥18–20K token 才有净收益（0.72–0.84×）； 10–25K 的常见中短任务上是 1.0–1.4×，即净开销（压缩省下的上下文盖不过调用与延迟）。
⇒ 建议：日常用「工具折叠」；确认会长跑（峰值 ≥20K）的会话再选「单压缩/双压缩」。
- 压缩收益主要来自三者共有的无损工具折叠；[A] 段浓缩是增益项而非主力。
- 判据看 last-fold：aCount/aFolded（命中率）、fallbackReasons（回退原因分型：truncated/empty/ noShrink/llmErr/payloadGate/maxCalls/budgetMs/keysErr）、keys、shrink。
注意 ms 会被机器休眠放大，不能当算力时间读。

已知取舍（如实说明）

1. 默认行为：多段转录与 standalone 默认关闭 ⇒ 本包默认行为与 0.1.8 逐字一致。
2. 本地小模型慢：4B 级浓缩一次 [A] 约 7~15s；一次折叠超预算就无损回退（转录照旧完整，只是没压缩）。
判「有没有压缩」看 calls/aFolded；ms 可为 0，也会被机器休眠放大（实测有 4.7h 的读数）。
3. 无 [R] 的两种正常情形：主模型 reasoning 未关（不做外置推理）；或该 preset 裁剪了工具集（此时账本记 skip-no-readonly-tools，不再报错）。
4. 装完必须重启 dsh web：客户端插件按名缓存，刷新页面不够。
5. 本包基于 @deepseek-ai/dsh 0.1.1-rc.2 验证；换 DSH 版本前请先核实。