前言¶
在 DSH 里跑长会话时，命令和 stdout 会一条接一条堆进上下文。宿主的 spill 策略只管「单条极大」的输出，compaction 相关插件往往要等压力上来才动手，中间那几万字符的「中等大块」仍会原样占窗口。dsh-compaction-basic 到约 80% 窗口才会用一次 LLM 写摘要，命令细节也容易丢。
下面介绍社区插件 dsh-session-fold（维护者 kennethfan，分类：工作流）：在每次 step 开始前（或你手动触发时），把较早的超长 tool/result 折成「头尾摘要 + 元信息 + spill 路径」的短替身，原文经宿主 ctx.spillStore 落盘。不调用 LLM，与 dsh-compaction-basic 互补而非替代。
这是什么¶
dsh-session-fold 对会话表面（surface）上的工具结果做确定性折叠：超过阈值的纯文本输出写入 session 作用域 spill 文件，日志里留下可回捞的替身。模型需要细节时按路径 read / grep，或通过插件提供的 recall 工具按序号或 pattern 取回。
仓库：kennethfan/dsh-session-fold
目录页：SkillHub 插件页
和现有机制的分工¶
| 现有机制 | 何时生效 | 留白 |
|---|---|---|
dsh-spill-policy |
单条 > 约 12500 估算 token，工具返回时 | 1–12k token 中等输出仍留在历史里 |
dsh-compaction-tool-result-pruner |
compaction 触发时裁 8k 字符以上结果 | 压力未到阈值则不跑 |
dsh-compaction-basic |
上下文约 80% 窗口 | 需 LLM 摘要，命令细节易丢 |
本插件补的是「成串累积、但还没把窗口顶满」这段空档：按压力或候选数量在 step 边界批量折叠，让上下文提前变瘦，从而减少触发 compaction-basic 的频率。
折叠后模型看到什么¶
替身大致如下（头 200 字符、尾 80 字符保留，中间是元信息与路径）：
<原文开头 200 字符>
…[输出已折叠] #3 bash command=go test ./...
原输出 812 行 / 61234 字符 / 58.7 KB
完整原文：/Users/kenneth/.dsh/.../spill/bash-2-....txt
回捞：read 或 grep 这个文件：/Users/kenneth/.dsh/.../spill/bash-2-....txt…
<原文结尾 80 字符>
#序号 对应原始事件 seq，便于 /unfold 与 session_fold_recall。
运行机制（要点）¶
- 钩子挂在
agent/pre-step或你执行的/fold。 - 若日志里存在未闭合的
compaction/start，整轮跳过，避免与 compaction 抢 surface。 - 从 surface 上选候选：非错误、非富内容、未折过、超阈值、不在保留窗口内的
tool/result。 - 上下文估算达到
foldAtRatio（相对模型窗口）或绝对foldAtTokens，或候选数 ≥minCandidates时触发。 - 阶段一：异步
ctx.spillStore.saveText落盘；阶段二：同步appendcompaction/prune（若体系已注册）与带surfaceOp: replace的tool/result替换。影子计价事件必须紧挨在 replace 之前，中间不能await。
折叠必须写成真正的 surface 替换事件（sourceEventSeqs 覆盖被遮蔽节点），保证回放与分叉可确定性重建。
安装与启用¶
已发布包（README 标注 v0.1.0，资产名固定）：
plugin_manager: action=install_bundle, target=https://github.com/kennethfan/dsh-session-fold/releases/latest/download/dsh-session-fold.tgz
本地开发目录：
plugin_manager: action=install_bundle, target=/path/to/dsh-session-fold
安装会向 profile 的 dsh.profile.bundles 追加 dsh-session-fold，并自动在 cordis.patch.yml 插入 session-fold 配置行。改代码后可用 set_plugin 对 entry 先关再开做 HMR 重载；是否载入新逻辑可看 cordis_inspect_query(host, Tool.listTools) 是否出现 session_fold_recall。
插件以当前 DSH 进程权限运行，安装前请自行阅读源码与 MIT 许可证 条款。
配置¶
两种方式等价，改的是同一份生效配置：
- 图形配置页（推荐）：设置侧栏「会话折叠压缩」，或插件页进入本包。12 个字段分常用 7 项与高级 5 项；编辑为本地草稿，点保存才写入 profile 的 Cordis patch。保存前做类型与范围校验，
foldThresholdChars必须大于headChars + tailChars + 160。 - 配置文件：在 profile 的
cordis.patch.yml用- id: session-fold整条覆盖 config（需写全要保留的字段）。
会话内只读查看：/fold-config。pruneRoot 故意不在配置页，只能在 cordis.patch.yml 手动设置。
常用默认值（完整表见 README）：
| 字段 | 默认 | 含义 |
|---|---|---|
auto |
true |
step 边界自动折叠 |
foldAtRatio |
0.25 |
上下文达窗口该比例时折叠 |
foldThresholdChars |
800 |
单条纯文本超过才折 |
headChars / tailChars |
200 / 80 |
保留头尾长度 |
retainTurns |
3 |
自动折叠时最近 N 轮不折（手动 /fold 不受限） |
minCandidates |
5 |
未达压力时的候选条数门槛 |
maxPerPass |
20 |
单次折叠上限 |
command、recallTool、prune 为运行期开关：关闭后调用会提示「已在插件配置里关闭」，不会从菜单消失。
典型用法¶
| 入口 | 作用 |
|---|---|
自动（auto: true） |
长会话无需操作 |
/fold |
立即折一轮，跳过压力与 minCandidates；进行中轮次只保护当前轮 |
/folds |
列出表面折叠项：序号、工具命令、原大小、原文路径 |
/unfold <序号> / /unfold all |
从日志恢复原文到 surface（append-only，可回放） |
/fold-config |
打印当前生效配置并标出与默认不同的项 |
/spill-prune |
预览或清理孤儿 spill 目录（见下） |
session_fold_recall |
模型按 seq 取全文，或 pattern 逐行搜索；无参则列清单 |
恢复语义要分清三层：
- 内容恢复：
/unfold与 recall 从会话日志原始事件取文，spill 被删仍可恢复。 - 上下文恢复：
/unfold把替身换回 surface，下一轮请求重新可见。 - 整段历史回滚：不支持；日志 append-only，只能新开会话或从备份恢复。
spill 手动清理¶
/spill-prune 默认预览，--apply 才删除。可按 --older-than N 天、--all 扩展范围。只处理 spill 根下名为 session-<12位hex> 的直接子目录，并与 ctx.sessionQuery.listSessions() 比对；归档会话仍算存活。根路径过浅或与 ~、~/.dsh 等相等时会拒绝执行。
适用场景与边界¶
适合：工具输出密集、单条动辄数千字符但仍低于 spill 单条阈值的智能体工作流；希望少触发 LLM compaction、又要在需要时能回捞完整 log 的场景。
边界（README 写明）：
- 只折
tool/result的纯文本；图片/文件块、isError: true不折。 - 不改 user/assistant 消息体；不合并工具调用结构。
- 批量 replace 会使 provider prompt cache 自首个改动消息起失效，故触发策略偏「压力达标再批折」。
- 单条仍极大时，折后约
head + tail + 元信息，无法把一条 200k 字符压到几十 token。 - spill 保留期限由
dsh-spill-local等宿主策略决定；本插件提供/spill-prune作补充。
结尾¶
dsh-session-fold 用确定性折叠在 step 边界给上下文「减肥」，零额外模型调用，并与 compaction 体系通过 surface 事件与影子计价对齐。需要试用可从 SkillHub 目录页进入说明，或直接在 GitHub 查看 README 与安装包。
- 目录页：https://www.skillhub.cn/plugins/kennethfan/dsh-session-fold
- GitHub：https://github.com/kennethfan/dsh-session-fold
