Icstick/dsh-work-continuity

DeepSeek Harness (dsh) 的 Work Continuity 插件——跨会话的工作状态显式持久化，和通用记忆分开管理。

设计铁律（与 ACP 一致）：记忆不负责替你把活干完。 目标、决策、下一步这些工作状态，不该混在记忆里被遗忘或被乱注入——它们是独立管理、随时可查的。

为什么需要它

和 agent 干活的人应该都熟这个场景：昨天干到一半，今天打开新会话，agent 一脸茫然——"我们昨天聊到哪了？"你只好翻聊天记录，重新交代一遍背景。

Work Continuity 把工作状态变成不用你记得记的事：目标、决策、下一步，工作自己留下痕迹；下次会话打开，agent 已经知道你在追什么。

三种捕获方式（v0.2.0）

早期版本只靠人敲 /checkpoint 命令——审计发现装了一周只有 1 次冒烟写入：功能不坏，是"要人记得敲命令"这件事本身不成立。现在有三层，互相兜底：

层	机制	覆盖的场景
事件自动捕获	监听宿主权威事件 goal/change（目标域每次变更必发）与 todo/write（任务清单每次写入必发）	agent 建了多步任务清单（≥2 项未完成）、用户设立/变更长期目标、目标完成/暂停/阻塞
LLM 自主决断	注册 work_state 模型工具 + 每轮注入当前工作摘要	对话里自然语言提出的构想、值得追踪的节点——LLM 看见摘要、自己决定记什么
显式命令	/checkpoint（人随时可查可改）	你想亲自盯着记的内容

• goal/change 事件会建档/更新目标与状态（complete→done、pause→paused…，clear 清空）；

• todo/write 事件只在该工作区还没有任何 WorkState 时自动建档（nextSteps 取自未完成任务）——已有手记内容不被每轮全量替换的 todo 覆盖；

• 每轮 pre-step 注入紧凑摘要（goal/status/focus/下一步/handoff，~150 token），消息以 source.kind: plugin:dsh-work-continuity 标记生产者；LLM 由此知道"正在追踪什么"，在节点主动用 work_state 工具更新；无状态不注入；已完成（done）默认也不注入（收尾语义），除非配置 injectWhenDone: true（2026-10-11 新增，默认 false = 行为不变）——一台机器把 status 设成 done 之后，它积压的下一步/未决项原本对整个会话都不可见，这个开关给那种场景一个出口。

• 压缩后重锚（2026-09-09）：监听 compaction/summary——压缩会把已注入的工作摘要从上下文里抹掉，而注入只在 step 1 发生。压缩后下一步无条件补注一次再清标记，解决同轮后续步骤看不到工作状态的问题。

• 设定点偏差检测（C5，2026-10-05）：监听 tool/call，确定性提取本次动作的目标（write/edit 的 file_path、bash 的命令首 token），与 WorkState 里 goal/focus/artifacts 能确定性提出的 scope（路径前缀、反引号词、带扩展名的文件名）比对；连续 3 次落在 scope 外 → 下一步 pre-step 注入一条提醒（约 100 token）并落 op=scope-drift 审计。不做语义判定（那是 LLM 候选区）。goal 提不出可识别 scope 时整体不工作（fail-open：宁可漏报，不误报）。

• 注入窗口取尾部 + cwd 属性路径修正（2026-10-11）：两个都是「看起来在、实际不生效」的静默缺陷，实测于 A 机（详见 docs/ops/dsh-state-hygiene-20261011.md）：

  1. decisions / unresolved 是只追加的日志，而注入一律 slice(0, N) 取数组头部 = 取最旧的 N 条。实测 223 条 decisions 时只注入 index 0,1，index 2..222 永不进入上下文；而注入进去的那条早在 index 23 就被「订正…这条记录不成立」推翻过。现在日志类改为 slice(-N) 取最新 N 条；next_steps 仍取头部——它是队列（next 追加 / done 移除），队首才是「下一个该做的」。
  2. 读会话 cwd 一律走 session.cwd，而 DSH 里 cwd 在 session.header.cwd 上（少了 header 一层）。可选链把「路径写错」和「字段没值」变成同一个 undefined，所以不报错、不抛异常，只是 ws:<hash> 分支整条变成死代码，所有会话静默落 user-global 桶。已收敛到 cwdOfSession() / cwdFromCtx() 两个 helper 并全量替换（读侧 5 处 + 工具伪造 session 的写侧 1 处）；判据与全文见 weaver software-code/wv-20261011-003。

  注：修 cwd 路径前必须先清干净库里带内容的 ws: 行——否则那些陈旧状态会被立刻命中并注进上下文。

• 注入调度器接线（v0.2.0，S1-P7 2026-09-05）：宿主 dsh-inject-scheduler 可用时注册 wc.work_state 段并按实际注入量上报；未挂 scheduler 时回退为 pre-step 直接注入（两路径互斥不叠加）。

小故事：昨天你说"想给工具箱加个 FFT 工具"就睡了。当时 agent 顺手把这个构想记进了 next steps。今天新会话一开，agent 第一眼就看到 [work-state] goal: 电子工具箱…——不用你重复半句，直接接着昨天的话往下干。

一个简单的例子

昨天你加班到半夜，临走前对 agent 说：

记住，下一步是把测试跑通。

它记下了。今天早上你打开电脑，敲一句：

/checkpoint show

目标、当时做的决策、下一步该干什么，全部列出来。你不用回忆，它也不用道歉。

命令

命令	说明	示例
/checkpoint goal <内容>	设置当前目标	/checkpoint goal 完成 M3 开发
/checkpoint decision <内容>	记录一个决策	/checkpoint decision 用 MIT 许可
/checkpoint next <内容>	添加下一步行动	/checkpoint next 合流组A
/checkpoint artifact <路径>	记录产物路径	/checkpoint artifact D:/out/report.pdf
/checkpoint unresolved <内容>	记录没解决的问题	/checkpoint unresolved 审批面板没显示
/checkpoint status <状态>	更新进度状态	/checkpoint status active（planned/active/blocked/paused/in_review/done）
/checkpoint handoff <内容>	写交接摘要（跨会话/跨 agent）	/checkpoint handoff 下个会话先跑全量测试
/checkpoint deadend <尝试> — <为何失败>	记录走过的死路与原因	/checkpoint deadend 直接改 save 签名 — 调用点太多
/checkpoint focus <内容>	设置当前焦点	/checkpoint focus 修回归
/checkpoint show	查看当前工作状态	/checkpoint show
/checkpoint done <n>	标记第 n 个下一步已完成；完成时把该条的 deadline/deliverable/verify 一起留痕（C10，2026-10-05，此前直接丢弃）	/checkpoint done 1
/checkpoint stats	使用统计（写入次数 / 完成率 / 各 scope 概览）	/checkpoint stats
/checkpoint clear	清空（重置全部字段，P1-2）	/checkpoint clear

work_state 模型工具（LLM 侧，同数据）

模型可见工具 work_state 与 /checkpoint 共享同一 store/渲染/审计：action 支持 goal/decision/next/artifact/unresolved/focus/handoff/deadend/status/done/show/export/clear。完成权分离（2026-09-09）：模型只能把目标推到 in_review（已交付、待验收），done 不可由模型设置——需人类执行 /checkpoint status done。工具另接受可选 version 参数做乐观并发：带上你读到的 version，库中版本已变则返回 WC_STALE_VERSION 并要求重读再写，避免并发静默覆盖。next 可带 deadline（ISO 日期或 YYYY-MM-DD）、deliverable（交付物/验收判据——完成判据=实测结果而非口头自报）与 verify（预期验证方式，C10 2026-10-05：测试/命令/截图/人工核），写入 next_meta 与 next_steps 下标对齐（P1-1）。done 现在会把该条的 deliverable/deadline/verify 一并留痕到 completedSteps 与审计（此前是直接丢弃）。注入摘要已渲染到期标注（T4 M4.5）：next 匹配 nextMeta[i].deadline → 「(dl YYYY-MM-DD)」，已过期 → 「⚠ 逾期」——模型每轮可见截止时间。工具描述明确告诉模型：用户提出新构想/目标、工作到值得追踪的节点、需要跨会话记住进度时调用；琐碎单步不要记。

设计取舍

人可核对是底线：无论哪层捕获，写进 work.db 的每一条都可以 /checkpoint show 查；全部写入在 work_audit 留痕（/checkpoint stats 聚合可见），绝不做不可见的"每轮 LLM 总结"。

演进路径：MVP 只做显式命令（/checkpoint）→ 发现没人记得敲 → 加事件自动捕获（goal/change、todo/write，确定性触发、无 LLM 猜测）→ 再补 LLM 自主决断（work_state 工具 + 摘要注入，覆盖自然语言构想）。

噪声控制：已有 WorkState 不被 todo 全量替换覆盖；done 状态默认不注入（injectWhenDone: true 可放开）；内容无变化不写库（diff 门控）；全部 fail-open——插件任何异常只记日志，绝不阻断对话。注入摘要含 handoff 一行（有则显示，100 字符上限）。

Agent 安装指南（面向自动化装配）

给需要在本机 dsh 装配本插件的 agent/脚本读；人工安装见下一节。 硬约束：① workDir 必须显式配置；② pnpm install 前先停 dsh（Windows native DLL 锁）； ③ 同 id 的 patch 条目是整体覆盖，不要重复插。

1. 定位 profile：<DSH_HOME>/profiles/<profile>/；先读 package.json，无 dsh.profile.bundles 键则 profile 未初始化，先初始化再继续。

2. 添加依赖（二选一）：

# A. GitHub 源：CLI 自动把声明 dsh.bundle 的包加入 dsh.profile.bundles
dsh plugin --profile <profile> add github:Icstick/dsh-work-continuity
# B. 本地开发：profile package.json dependencies 加 "dsh-work-continuity": "link:<绝对路径>",
#    并在同文件 dsh.profile.bundles 数组追加 "dsh-work-continuity"

⚠️ dsh plugin add 不会写配置条目——第 3 步必须做。

3. 写配置：编辑 profile 根 cordis.patch.yml（无则新建）：

- id: work-continuity
  name: dsh-work-continuity
  config:
    workDir: C:\path\to\work-state   # 必填：工作状态库绝对路径；DSH_HOME 环境变量不可靠

4. 安装并重启：停 dsh → profile 目录 pnpm install → 重启 dsh。

5. 验证：

• 数据：<workDir>/work.db 存在
• 命令：对话里 /checkpoint show 正常响应（无状态时也应有明确空态提示）

故障速查：/checkpoint 不存在 → commands 服务加载晚于插件就绪属正常时序，插件会 等待注册；数据落在意外位置 → workDir 没显式配置（务必补）。

安装

GitHub 一键安装：dsh plugin --profile <name> add github:Icstick/dsh-work-continuity （bundle patch 会自动挂载 work-continuity 条目）。装完后仍需在 profile 的 cordis.patch.yml 给该条目补 config.workDir（数据目录必须显式）并重启； 完整三步与字段说明见下。

三步（和 dsh-adaptive-context 一样）：

1. profile package.json：

{
  "dependencies": {
    "dsh-work-continuity": "link:D:/path/to/dsh-work-continuity"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-work-continuity"]
    }
  }
}

2. profile cordis.patch.yml：

- id: work-continuity
  name: dsh-work-continuity
  config:
    workDir: C:\path\to\work-state   # 必须显式写

3. 安装并重启：

cd <profile 目录>
pnpm install
# 重启 dsh

配置

字段	类型	默认	说明
workDir	string	必填	工作状态数据目录（work.db 所在）。必须显式指定，DSH_HOME 环境变量不可靠
debug	boolean	false	调试日志

数据位置

• workDir/work.db（SQLite 单文件）——全部工作状态
• 未配置 workDir 时落 $DSH_HOME/dsh-work-continuity/，终兜底 ~/.dsh/dsh-work-continuity/（P2-2 根治 2026-09-07：旧实现曾相对 cwd 落库，仓库内残留 work.db 已清）
• 数据是你的：卸载不删；装回来即恢复

卸载

1. 从 package.json dependencies 移除 dsh-work-continuity
2. 从 dsh.profile.bundles 移除包名
3. pnpm install 后重启

故障排查

症状	原因 / 处理
/checkpoint 命令不存在	commands 服务随 bundle 加载顺序可能晚于插件就绪——插件会等它出现再注册；还不行就检查 bundle 挂载
数据落在意外位置	旧版本曾相对 cwd 落库（P2-2 已根治，仓库内残留已清）；workDir 建议显式配置，未配置按 $DSH_HOME/dsh-work-continuity → ~/.dsh/dsh-work-continuity 兜底（稳定绝对路径）

开发

node test/work.test.mjs

仓库级开发计划与问题登记（backlog）：docs/DEVELOPMENT-PLAN.md。

License 与致谢

MIT License。参考项目致谢见 ACKNOWLEDGMENTS.md。

设置页（顶层 section，v0.2.0）

• 位置：DSH Web 设置 → 顶层 section「工作连续性（Work Continuity）」（与费用/Vision Router 同层，v0.2.0 起）
• 机制：host 侧注册 settings namespace（work-continuity），client bundle（lib/client.js， 由 node scripts/build-client.mjs 生成）注册设置卡片；保存写入 settings.yaml
• 生效语义：保存后重启生效（apply 时 settings 值覆盖 cordis Config）
• 字段：workDir（重启生效）/ debug

work_state 工具动作（2026-10-19）

action	用途	备注
goal / focus / status / handoff / deadend	目标、焦点、状态、交接、死路	status 只能推到 in_review；done 由人确认
decision / next / artifact / unresolved	追加一条	next 可带 deadline / deliverable / verify
done	标记第 n 个 next 完成	连同 meta 进 completed_steps
show [section]	查看	头部带 scope / version / 计数；section 取 goal / decisions / unresolved / next / artifacts / handoff / all
edit / retire	单条改写 / 退役	必须带 expect（目标条目当前内容的开头）；对不上就拒绝并回显当前内容。retire 的原文与理由进 work_audit，不物理删除；retire next 同步 nextMeta，且不计入 completed_steps（退役≠完成）
stats	各 scope 用量与完成率
clear	清空	清前自动落一份 md 快照到 <data>/archive/clear-<ts>.md

edit / retire 是给「账本需要整理」用的：此前只能追加，想删一条得绕开插件写 SQLite，既跳过 version 守卫，也不留审计。现在改成工具内动作，带条目级 CAS 与审计。