前言¶
在 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
