Introduction¶
In a DeepSeek Harness (DSH) environment, the context compression mechanism clears working memory, causing agents to lose critical facts after a compression window. Meanwhile, automatically injected context consumes tokens and trains the model to ignore that information. The @xiyiyiru/dsh-state plugin provides persistent state management through plain text files, ensuring working facts survive compression and recovery while maintaining zero automatic injection into requests.
Core Features¶
This plugin provides two main parts:
* Plain text session notebook: for recording and persisting working facts.
* Task stack tools: for managing execution order and locked state of multi-step tasks.
Installation and Enabling¶
Installing the plugin requires specifying a profile name. After installation, the plugin handles dependencies automatically.
dsh plugin --profile <name> add @xiyiyiru/dsh-state
Storage Mechanism¶
All state data is stored in plain text under the session workspace directory at <session-cwd>/.mycel/state/<sessionId>/. The directory contains two core files:
* notebook.md: the notebook file; each add_state call appends a section.
* focus.json: the task stack file; the bottom frame is the currently active task.
Core Operations¶
The operations provided by the plugin are divided into notebook operations and task stack operations.
Notebook Operations¶
| Tool | Semantics | Description |
|---|---|---|
add_state |
Append | Appends a record to the end of the notebook. If a correction is needed, append a new line instead of overwriting. |
read_state |
Read | Reads the full notebook content and size. When the notebook exceeds 8K characters, a compression hint is appended. |
compact_state |
Replace | Compaction operation. First reads, then rewrites the entire file with a summary. |
add_state should be used as a hard trigger in the following cases:
1. The user made a decision or correction.
2. A critical fact or root cause was established.
3. A multi-step task is started (including goals and acceptance criteria).
4. A milestone is completed (including conclusions and artifact paths).
Task Stack Operations¶
| Tool | Semantics | Description |
|---|---|---|
focus_task |
Push | Locks the current task, automatically pushes it to the bottom of the stack, and starts processing a new task. |
focus_complete |
Pop | Declares the current task completed, records a one-line conclusion, and falls back to the previous task. |
When a task is interrupted, use focus_task to lock the blocking point, and after resolving it, return to the main task via focus_complete.
Design Constraints¶
The plugin follows these design principles:
* Zero automatic injection: the notebook does not appear automatically in requests; tokens are consumed only when read_state is explicitly called.
* Append/replace only: no edit or delete verbs are provided, ensuring deterministic semantics.
* Zero session events: the plugin does not write to session logs, avoiding conflicts with DSH’s log vocabulary.
* Mode-independent: the task stack is decoupled from working modes and is responsible only for task order.
Use Cases and Notes¶
This plugin is suitable for DSH agent projects that need to persist working facts and want full control over context injection behavior.
Notes:
* The plugin runs with the permissions of the current DSH process; ensure write permission to the workspace directory.
* It is recommended to inspect the source code and license (MIT) before installation.
* focus.log is an auxiliary log for grepping task history; focus.json is the authoritative state.
References¶
- Plugin directory: https://www.skillhub.cn/plugins/xiyiyiru/dsh-state
- Source code: https://github.com/xiyiyiru/dsh-state