本地編碼智能體在處理長週期任務時，通常依賴鬆散的 STATUS.md 維護約定。這種做法容易導致狀態脫節、文件結構混亂，甚至因爲頻繁讀取文件而浪費 Token。dsh-local-long-horizon 插件將這一過程轉化爲由宿主管理的結構化 Vault，並提供經過驗證的 Agent 工具，確保任務狀態在 DeepSeek Harness Web UI 中可見且可維護。
核心功能¶
該插件提供以下核心能力：
- 宿主管理狀態：狀態存儲在宿主側，而非依賴 Agent 自行維護文件。
- 結構化 Vault：數據存儲在 JSON 格式的 Vault 中，
STATUS.md是其單向投影。 - 工具驗證：提供一系列經過驗證的 Agent 工具，用於讀寫狀態。
- 注入文件：提供一個極小的注入文件用於斷點續記。
- UI 集成：在右欄提供“Long horizon”面板，並在 Composer dock 提供芯片顯示。
- Agent 工具集：包含初始化、獲取、設置下一步、設置進行中、完成、阻塞/解鎖、開關控制等工具。
安裝與啓用¶
安裝插件需要使用 DeepSeek Harness 的 Web Profile。
1、在終端執行以下命令安裝插件：
dsh plugin --profile web add dsh-local-long-horizon
2、安裝完成後，重啓 dsh web 服務以加載插件。重啓後，刷新瀏覽器頁面即可看到新功能。
典型用法¶
啓用後，Agent 可以通過工具鏈接管任務狀態。
1、初始化：使用 status_init 啓用長週期追蹤。
2、設置下一步：使用 status_set_next 替換 Next 列表中的項目（數量限制爲 0-3）。
3、設置進行中：使用 status_set_inflight 標記當前正在執行的任務，必須提供非空的 summary。
4、標記完成：使用 status_mark_done 記錄已完成的任務，推薦附帶 verify 字段。
5、維護 AGENTS.md：在項目根目錄保留一個 AGENTS.md 文件作爲“膠水”，DSH 會將其注入到 Agent 指令中，指導 Agent 讀取注入文件並使用狀態工具。
Agent 工具列表¶
| 工具名 | 功能 |
|---|---|
status_init |
創建或刷新 Vault，開啓長週期追蹤 |
status_get |
獲取完整的結構化記錄 |
status_set_next |
替換 Next 列表（最多 3 項） |
status_set_inflight |
設置當前進行中的任務 |
status_clear_inflight |
清除進行中的任務 |
status_set_phase |
設置短週期的階段標籤 |
status_mark_done |
標記任務完成（可附帶 verify 和 rotateNext） |
status_block / status_unblock |
標記或取消阻塞狀態 |
status_set_enabled |
開啓或關閉長週期追蹤 |
status_ping |
探測 Host 健康狀態 |
注意事項與架構¶
系統要求¶
- Node.js：必須安裝 Node.js >= 20。
- DSH 版本：已驗證兼容 DeepSeek Harness
0.1.7-rc.2。
限制與約束¶
- Next 限制：Next 列表最多隻能容納 3 個項目，第四個會被拒絕。
- In-flight 要求：設置進行中任務時，
summary字段不能爲空。 - Done 記錄：標記完成時，
verify字段是推薦的，缺失時僅會警告。 - 開關控制：當追蹤功能關閉時，所有會修改狀態的工具都會拒絕執行，注入文件會凍結爲單行
DISABLED。 - 同步提示：僅在面板中顯示同步提示（如 git 分支變化），Dock 芯片不顯示。
數據流向¶
- Vault：數據源是
~/.dsh/storages/dsh-local-long-horizon/<taskId>.json。 - 注入文件：智能體實際讀取的綁定狀態文件爲
<cwd>/.dsh/task-status-inject.md。 - Markdown：
<cwd>/STATUS.md是根據 Vault 內容生成的，每次變更都會被覆蓋。 - 無文件依賴：插件沒有對宿主文件系統的讀取依賴，通過 DSH 提供的
ctx.tools服務註冊工具。
總結¶
dsh-local-long-horizon 通過將狀態管理從 Agent 的“軟約定”轉變爲宿主的“硬結構”，解決了長週期任務中的狀態追蹤問題。配合 DeepSeek Harness 的 Web UI，它爲開發者提供了一個可視化的任務看板和可靠的狀態回寫機制。
