前言¶
用一個 AI 編碼智能體跑長任務時，常見的情況是：任務跑到一半需要暫停，或者要把上下文交給另一個 agent、另一位開發者繼續。普通的交接方式是把對話記錄或工作筆記原樣丟過去，接收方拿到的是一段描述性文字——任務做到哪一步、哪些決策已確定、哪些驗證已通過，都要靠人重新梳理，而且沒法確認工作區和交接時還是同一個狀態。
dsh-workstate 解決的就是這個問題。它把智能體當前的工作捕獲成機器可讀的狀態包，並在恢復前先校驗工作區是否仍然匹配，再注入狀態。下面介紹這個插件的定位、功能與用法。
這是什麼¶
dsh-workstate 是一個面向 DeepSeek Harness 的 local-first 插件，作者是 luoyuejun9，許可證爲 MIT，當前版本 0.1.0。
它捕獲的是智能體正在做什麼：任務狀態、進度、決策、失敗、驗證、變更路徑、下一步動作，以及一個 Git 完整性指紋。README 明確說明，它不是對話記錄的導出。
核心是四個動作：
- checkpoint：暫停並保存當前工作
- transfer：爲其他 agent 或開發者創建可分享的導出
- resume：校驗並注入已有狀態包，絕不更改 Git 狀態
- diff：按穩定的 work-item ID 比較兩個 checkpoint
核心功能¶
命令¶
安裝後可以使用以下斜槓命令：
/workstate checkpoint [note]
/workstate transfer [target]
/workstate list
/workstate inspect [id]
/workstate diff <from> <to>
/workstate validate [id]
/workstate resume [id]
/workstate resume [id] --allow-diverged
提供給模型的工具¶
除了斜槓命令，插件還會向模型提供 workstate_capture、workstate_list、workstate_read、workstate_diff、workstate_validate、workstate_resume 這組工具，模型可以在合適的時機自行調用，不必完全依賴人工敲命令。
安裝與啓用¶
插件需要 Node.js 22.19+ 與 DeepSeek Harness 0.1.0-rc.6。安裝命令面向 web profile：
dsh plugin --profile web add dsh-workstate
安裝完成後，還需要在 ~/.dsh/profiles/web/cordis.patch.yml 中手動添加以下 insert（保留文件中已有的行）：
- insert:
- id: workstate
name: dsh-workstate
然後重啓 DSH。如果使用本地源碼檢出做臨時測試，可以把等價的 patch 指向本地安裝的包。經過上面的步驟，插件即可在 web profile 中生效。
存儲與安全設計¶
這部分是插件的重點，先說存儲，再說安全邊界。
狀態包格式爲 dsh.workstate/v1alpha1，存儲在 .dsh/workstate/ 目錄下。checkpoint 歷史只保存在本地且被 gitignored，只有 transfer 導出纔有意設計爲可被 Git 跟蹤。
狀態包只包含路徑與哈希，不包含文件內容或 diff；持久化之前會拒絕已知憑據模式，避免把敏感信息寫進狀態包。
resume 時的校驗會對比 Git 分支、commit、髒狀態與內容指紋，出現分歧時默認 fail closed，即拒絕恢復。如果確認分歧可以接受，再用 --allow-diverged 顯式放行。
另外，插件本身絕不執行 checkout、reset、stash、stage、commit 或 push，Git 狀態的變更始終由使用者自己控制。
典型工作流¶
結合上面的能力，一次典型的交接流程是：
1、當前 agent 執行 /workstate checkpoint [note]，把任務狀態、進度、決策、失敗、驗證、變更路徑、下一步動作與 Git 完整性指紋保存爲狀態包。
2、用 /workstate list 查看已有 checkpoint，用 /workstate inspect [id] 查看某個 checkpoint 的詳情。
3、需要交給其他 agent 或開發者時，執行 /workstate transfer [target] 生成可分享的導出。
4、接收方執行 /workstate resume [id]。resume 會先校驗 Git 分支、commit、髒狀態與內容指紋，通過後才注入狀態包；出現分歧時會失敗退出，必要時用 --allow-diverged 放行。
5、恢復後如果想比較兩個工作時點，用 /workstate diff <from> <to> 按 work-item ID 對比，或用 /workstate validate [id] 做校驗。
適用場景與注意事項¶
適合的場景：
- 長任務中途暫停，之後由同一個或另一個 agent 恢復
- 在 agent 與開發者之間移交工作，兩個方向都可以
- 需要對兩個工作時點做結構化比較，而不是靠肉眼讀對話記錄
注意事項：
- 插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證。本項目爲 MIT 許可，源碼在 GitHub 上可直接審閱。
- 插件版本爲 0.1.0，依賴 DeepSeek Harness 0.1.0-rc.6；peerDependencies 包括 @deepseek-ai/dsh-agent、dsh-commands、dsh-llm、dsh-tools（均爲 0.1.0-rc.6）與 @deepseek-ai/cordis 4.0.1，安裝時注意版本匹配。
- 想參與本地開發，克隆倉庫後先運行
npm install，再運行npm run check，即可完成類型檢查、測試與構建。
結尾¶
dsh-workstate 做的事情不復雜：把智能體的工作狀態落成結構化、可校驗的包，讓交接不再依賴一段描述性文字，也不用擔心工作區悄悄變了。對需要多 agent 協作或人機接力的工作流來說，這是一個值得試一下的插件。
- 目錄頁：https://www.skillhub.cn/plugins/luoyuejun9/dsh-workstate
- GitHub：https://github.com/luoyuejun9/dsh-workstate
需要說明的是，skillhub.cn 是獨立的社區插件目錄站點，與 DeepSeek / 幻方沒有官方從屬關係。DSH 的理念是「一切皆插件」，像 dsh-workstate 這樣的社區插件正是這個生態的組成部分。
