工作续接 Icstick/dsh-work-continuity

dsh-work-continuity

Awesome DSH Plugin

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

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

为什么需要它

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

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

三种捕获方式（v0.2.0）

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

| 层 | 机制 | 覆盖的场景 |
| 事件自动捕获 | 监听宿主权威事件 goal/change（目标域每次变更必发）与 todo/write（任务清单每次写入必发） | 智能体建了多步任务清单（≥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 工具」就睡了。当时智能体顺手把这个构想记进了 next steps。今天新会话一开，智能体第一眼就看到 [work-state] goal: 电子工具箱…——不用你重复半句，直接接着昨天的话往下干。

一个简单的例子

昨天你加班到半夜，临走前对智能体说：

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

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

/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> | 标记第 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 快照到 /archive/clear-<ts>.md |

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