前言¶
下面介绍一个 DeepSeek Harness（DSH）插件：flowctx-dsh。
它面向智能体编程中常见的上下文管理问题：随着会话变长，工具输出不断累积，历史细节逐渐模糊，模型可能重复搜索、遗忘约束，或者把早期失败路径和关键标识符弄丢。已有做法通常依赖基础压缩或摘要，但摘要可能丢失失败路径，工具结果压缩后也可能难以原样取回。
flowctx-dsh 在 dsh-compaction-basic 之上做加性扩展：摘要风格更贴近工程交接，工具结果压缩后可按 hash 取回原文，历史可折叠成分层摘要节点，并提供一个可选的 working_memory 编辑工具。所有扩展均可逐项开关；全部关闭时，行为等同于仅调整了摘要风格的 dsh-compaction-basic。
插件定位¶
flowctx-dsh 是面向 DSH 的本地优先上下文引擎，由 Ayou-Claw 维护。
- 名称：
flowctx-dsh - 版本：
0.1.0 - 许可证：
MIT - GitHub：
https://github.com/Ayou-Claw/flowctx-dsh
它不是替代 DSH 基础压缩能力，而是在其上做扩展：
- 摘要输出面向工程师交接笔记；
- 历史可后台折叠成分层
summary nodes； - 超阈值工具结果可逆投影；
- 提供可选的工作记忆工具；
- 提供
flowctx_retrieve用于取回被压缩材料。
核心能力¶
工程师交接笔记摘要¶
这项能力挂在 agent/pre-step，替换原摘要提示词。
它要求摘要输出 6 段式交接笔记，并专节保留两类关键信息：
- 失败路径；
- 逐字标识符。
与通用叙述式摘要相比，它更适合软件调试、代码修复、长期任务推进等场景，因为“哪条路试过了”“哪个函数、路径、commit 或 session id 出现过”往往比笼统总结更重要。
该能力默认开启。
分层 DAG 摘要¶
这项能力同样挂在 agent/pre-step，但走后台 fire-and-forget 路径。
它把历史折叠成分层 summary nodes，而不是只维护一条滚动摘要。对于长会话来说，早期不同话题可以保留为不同层级的摘要节点，避免全部被压成一段泛化描述。
该能力默认开启。
可逆工具结果投影¶
这项能力挂在 tools/post-execute。
当工具返回结果超过阈值时，它会对 tool result 做结构化压缩。压缩时不是直接丢弃原文，而是：
- 将原文按 hash 存入
CompressionStore； - 在上下文中保留可取回引用；
- 支持
byte-exact取回。
也就是说，大段日志、长工具输出可以先进入压缩引用，后续需要时再按原样恢复。
该能力默认开启。
可编辑工作记忆¶
这项能力通过 flowctx_scratch_* 工具提供，用于维护 <working_memory> 块。
它默认关闭。开启后，模型可以通过以下工具维护工作记忆：
flowctx_scratch_appendflowctx_scratch_replaceflowctx_scratch_rethink
适合需要让 agent 主动记录当前目标、待办事项、不可遗忘结果的任务。
取回工具：flowctx_retrieve¶
flowctx_retrieve 是配套取回工具。
它支持两类取回：
- 按
hash取回被投影压缩的原文； - 按
node id取回指定层级的交接笔记。
这使得压缩不是单向丢失，而是“先引用、后恢复”。
安装与启用¶
下面以 web profile 为例。
1、安装插件¶
执行：
dsh plugin --profile web add flowctx-dsh
2、加入 profile patch 层¶
编辑：
~/.dsh/profiles/web/cordis.patch.yml
加入：
- insert:
- id: flowctx-dsh
3、重启 DSH web¶
dsh web
4、验证加载¶
dsh --profile web --dump-config | grep flowctx
如果配置已加载，命令输出中应能看到 flowctx 相关配置。
典型用法¶
取回被投影压缩的原文¶
当工具结果被投影压缩后，可以用：
flowctx_retrieve(hash="…")
按 hash 取回原文。
取回指定层级的交接笔记¶
flowctx_retrieve 也可以按 node id 取回指定层级的交接笔记。
这适合在长会话中回看早期阶段的任务目标、已尝试方案、失败路径或关键标识符。
使用 scratchpad 维护工作记忆¶
开启 scratchpad 后，可以使用：
flowctx_scratch_appendflowctx_scratch_replaceflowctx_scratch_rethink
维护 <working_memory>。
该能力默认关闭，适合明确希望 agent 主动维护短期工作记忆的场景。
配置与状态¶
所有配置项均为可选。未配置时，flowctx-dsh 的行为等同于 dsh-compaction-basic，区别主要是摘要风格不同。
默认状态：
- 工程师交接笔记摘要：默认开；
- 分层 DAG 摘要：默认开；
- 可逆工具结果投影：默认开；
- 可编辑工作记忆：默认关。
状态存储有两档：
- 不设置
stateDir时，退化为纯内存 + TTL，会话内可恢复； - 设置
stateDir后，压缩引用、summary nodes与 scratchpad 共用一个数据库句柄，落盘到：
<stateDir>/flowctx.sqlite
依赖方面，peerDependencies 指定了：
@deepseek-ai/cordis ^4.0.1
以及多个：
@deepseek-ai/* ^0.1.0-rc.6
依赖。
适用场景与注意¶
适合以下使用方式：
- 使用 DSH 做长会话智能体编程；
- 需要保留失败路径和关键标识符；
- 需要把长工具结果压缩成引用，并在后续按需恢复；
- 希望历史摘要分层保留，而不是只保留一条滚动摘要；
- 希望按需开启工作记忆编辑。
需要注意：
- 插件会以当前
dsh进程权限运行； - 安装前应检查源码、许可证与依赖；
- 当前版本为
0.1.0，许可证为MIT； - DSH 版 SWE-bench 评测正在进行中，结果尚未提供；
- 完整配置项继承自
dsh-compaction-basic的完整列表在已核实资料中被截断，本文不展开。
结尾¶
flowctx-dsh 的价值在于：它把 DSH 的上下文压缩从“摘要掉历史”推进到“压缩、分层、保留、可取回”的工程记忆模型。对于长会话 agent 编程来说，这种可恢复的上下文组织方式，比单纯缩短 prompt 更关键。
GitHub：https://github.com/Ayou-Claw/flowctx-dsh
目录页地址未在已核实资料中给出。
