前言¶
用一个 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 这样的社区插件正是这个生态的组成部分。
