前言¶
下面介紹一個 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
目錄頁地址未在已覈實資料中給出。
