前言¶
在 DeepSeek Harness (DSH) 環境中，上下文壓縮機制會清理工作記憶，導致智能體在壓縮窗口後丟失關鍵事實；而自動注入的上下文則會消耗 token 並訓練模型忽略該信息。@xiyiyiru/dsh-state 插件通過純文本文件提供持久化狀態管理，使工作事實在壓縮和恢復後依然存在，同時保持對請求的零自動注入。
核心功能¶
該插件提供兩個主要部分：
* 純文本會話筆記本：用於記錄和持久化工作事實。
* 任務棧工具：用於管理多步驟任務的執行順序和鎖定狀態。
安裝與啓用¶
安裝插件需要指定一個配置文件名稱。安裝完成後，插件會自動處理依賴項。
dsh plugin --profile <name> add @xiyiyiru/dsh-state
存儲機制¶
所有狀態數據以純文本形式存儲在會話工作區目錄下，路徑爲 <session-cwd>/.mycel/state/<sessionId>/。該目錄包含兩個核心文件：
* notebook.md：筆記本文件，每次調用 add_state 會追加一段內容。
* focus.json：任務棧文件，底部的幀爲當前正在進行的任務。
核心操作¶
插件提供的操作分爲筆記本操作和任務棧操作。
筆記本操作¶
| 工具 | 語義 | 說明 |
|---|---|---|
add_state |
追加 | 向筆記本末尾添加一條記錄。若需修正錯誤，應追加新行而非覆蓋。 |
read_state |
讀取 | 讀取完整筆記本內容及大小。當筆記本超過 8K 字符時，會追加壓縮提示。 |
compact_state |
替換 | 壓縮操作。先讀取，然後用摘要重寫整個文件。 |
add_state 在以下情況應作爲硬觸發使用：
1. 用戶做出了決策或修正。
2. 建立了關鍵事實或根因。
3. 開始一個多步驟任務（包含目標與驗收標準）。
4. 完成了一個里程碑（包含結論與產物路徑）。
任務棧操作¶
| 工具 | 語義 | 說明 |
|---|---|---|
focus_task |
入棧 | 鎖定當前任務，自動將其推入棧底，開始處理新任務。 |
focus_complete |
出棧 | 宣佈當前任務完成，記錄一行結論，並回退到上一個任務。 |
當任務中斷時，可以使用 focus_task 鎖定阻礙點，解決後通過 focus_complete 返回主任務。
設計約束¶
該插件在設計上遵循以下原則：
* 零自動注入：筆記本不會在請求中自動出現，只有顯式調用 read_state 時纔會消耗 token。
* 僅追加/替換：不提供編輯或刪除動詞，確保語義的確定性。
* 零會話事件：插件不寫入會話日誌，避免與 DSH 的日誌詞彙表衝突。
* 無模式依賴：任務棧與工作模式解耦，僅負責任務順序。
適用場景與注意¶
該插件適合需要持久化工作事實且希望完全控制上下文注入行爲的 DSH 智能體項目。
注意：
* 插件以當前 DSH 進程的權限運行，請確保對工作區目錄有寫入權限。
* 安裝前建議檢查源碼與許可證（MIT）。
* focus.log 是輔助日誌，用於 grep 查看任務歷史，權威狀態以 focus.json 爲準。
參考資源¶
- 插件目錄：https://www.skillhub.cn/plugins/xiyiyiru/dsh-state
- 源代碼：https://github.com/xiyiyiru/dsh-state
