dsh-workspace-handoff
v0.2.0
Published
Workspace session handoff toolkit for DeepSeek Harness: pack the current working state (goal, decisions, open tasks, notes plus a glob-expanded context file manifest with sha256 fingerprints) into a portable handoff bundle, migrate it to another workspace
Maintainers
Readme
dsh-workspace-handoff
工作区会话迁移插件(零运行时依赖,仅 Node 内置模块)。
把一个工作区里「干到哪儿了」打包成可迁移的 handoff 包,搬到另一个工作区根后自动重映射绝对路径、体检文件漂移,并落地成人类可读的 HANDOFF.md + 机器可读的 handoff.json。适用于换机器、换目录、换盘符,或把 A 仓库的进度接到 B 仓库继续干。
- 源码:https://github.com/geeklei/dsh-plugins/tree/main/dsh-workspace-handoff
- npm:https://www.npmjs.com/package/dsh-workspace-handoff
- 协议:MIT
功能说明
五个工具:
| 工具 | 作用 | 关键能力 |
|---|---|---|
| pack_handoff | 采集当前工作状态,打成 handoff 包(JSON 返回) | 目标 / 关键决策 / 未完成任务 / 备注;按 glob 展开上下文文件清单(相对路径 + 大小 + mtime + sha256);剪枝依赖与产物目录、符号链接防环、文件数预算;可选带 .journal 近期日志;包内含规范化 JSON 的 sha256 完整性摘要 |
| migrate_handoff | 把包迁移到另一个工作区根,只出报告不落盘 | 状态文本内的来源根前缀重映射(容忍斜杠反斜杠混写、Windows 盘符大小写);漂移检测五态(未变 / 已改 / 改名 / 缺失 / 新增);接续结论 clean / renamed / dirty / unchecked |
| apply_handoff | 在目标工作区落地接续产物 | 写 .handoff/HANDOFF.md 与 .handoff/handoff.json;同名冲突策略 overwrite / skip / versioned;支持 dry_run 只看计划;落地包重算完整性并记录迁移溯源 |
| diff_handoff | 对比两个 handoff 包,只读不落盘(v0.2) | 目标 / 决策 / 任务 / 备注逐项差异;清单文件五态对比(相同 / 内容已变 / 改名移动 / 仅 a 有 / 仅 b 有,缺哈希时保守归入 uncertain);结论 identical / state_diverged / files_diverged / diverged |
| merge_handoff | 合并两个 handoff 包为一个新包(v0.2) | 决策并集去重;任务按文本并集(任一侧完成即完成,可改策略);清单按路径并集、同路径默认较新侧为准;notes 默认拼接;产物可直接 apply_handoff 落地 |
handoff 包结构(schema 为 handoff/v1):
{
schema, kind, created_at, producer,
source: { root, platform, label },
state: { goal, decisions, open_tasks, notes, journal? },
context: { patterns, files[{path,size,mtime,sha256}], stats },
integrity: { algo, digest }
}经 merge_handoff 产出的包会多一个 merged 字段(两侧来源、较新侧、合并策略),经 apply_handoff 落地的包带 migrated 字段——两者可并存,便于溯源。
设计要点:
- 搬的是工作状态,不是消息流水:
goal/decisions/open_tasks由模型自己声明,插件不读 dsh 会话历史,因此跨宿主、跨版本都能用,也不受会话导出格式变化影响。 - 清单只记相对路径(统一
/分隔):这是换机器、换盘符仍可解的前提;绝对路径只出现在source.root与文本描述里,迁移时按前缀重映射。 - 完整性可验:对不含
integrity的包做键升序规范化 JSON 后取 sha256;字段乱序不影响摘要,手工改内容会被检出。
安装
npm install dsh-workspace-handoff本地开发调试(Debug patch):新建 debug.patch.yml
- insert:
- id: workspace-handoff
name: "E:/dsh-plugins/dsh-workspace-handoff/index.js"使用说明
1. 在来源工作区打包
const bundle = await tools.pack_handoff({
goal: "续写架构实战合集第 21 篇并设定时发表",
decisions: ["封面口径沿用浅底蓝字模板", "交付清单为唯一状态来源"],
open_tasks: ["写完 21 篇", { text: "已发 01 篇", done: true }],
notes: "源码目录 E:/work/arch-notes/src,配图脚本在 tools 下",
files: ["**/*.md", "src/**/*.ts"],
include_journal: true,
})返回的 JSON 字符串原样保存(写入文件或直接带到另一台机器均可),也可只把 files 省掉——那时包内只有状态没有清单。
2. 在目标工作区迁移
const report = await tools.migrate_handoff({
bundle, // JSON 字符串,或 handoff.json 的路径
target_root: "F:/new-machine/arch-notes",
})关注 verdict:
clean清单文件全部一致,可直接接续renamed内容都在、只是路径改了(改名或移动),按drift.moved里的新路径读dirty有缺失或内容变更,接续前先确认原因
3. 落地接续简报
await tools.apply_handoff({
bundle,
target_root: "F:/new-machine/arch-notes",
mode: "versioned",
dry_run: false,
})生成 目标工作区/.handoff/HANDOFF.md(目标、决策、任务复选框、文件清单表、漂移表、近期日志、备注)与 handoff.json。在新工作区里让模型先读 HANDOFF.md 即可接续。
主要参数:
| 参数 | 类型 | 说明 |
|---|---|---|
| goal | string | 必填,≤500 字符 |
| decisions / files / prune | array | 字符串数组;files 为 glob |
| open_tasks | array | 元素为字符串,或含 text 与 done 的对象 |
| notes | string | ≤4000 字符,其中绝对路径会被重映射 |
| root / target_root | string | 工作区根;root 默认当前目录 |
| hash / check / strict / dry_run / force / include_journal | boolean | 见上 |
| a_bundle / b_bundle | string | diff_handoff / merge_handoff 必填:两份包,JSON 字符串或文件路径 |
| goal_from / notes_mode / file_policy / done_policy | string | merge_handoff 合并策略,非法取值直接报错 |
| max_files / max_hash_bytes / journal_limit / top | number | 预算类参数,越界或传字符串会被拒 |
4. 两份包对比与合并(v0.2)
同一件事在两台机器各自推进、或一天内打了多个包时,用 diff_handoff 看清差异,用 merge_handoff 收拢成一份:
const d = JSON.parse(await tools.diff_handoff({
a_bundle: packOnLaptop, // 第一份包:JSON 字符串或文件路径
b_bundle: packOnDesktop, // 第二份包
}))
// d.verdict: identical / state_diverged / files_diverged / diverged
// d.state.open_tasks.status_changed: 两边都写过的任务谁改了完成状态
// d.files.moved: 一侧改名/移动的文件(按内容 sha256 互相认领,一份内容只认领一次)
const merged = await tools.merge_handoff({
a_bundle: packOnLaptop,
b_bundle: packOnDesktop,
goal_from: "newer", // newer(默认)/ a / b
file_policy: "newer", // 同路径冲突以哪侧为准
})
await tools.apply_handoff({ bundle: merged, target_root: "F:/new/arch-notes" })合并策略默认「谁也不丢」:决策与任务取并集、同一条任务任一侧标记完成即视为完成、文件清单同路径以较新一侧条目为准。notes 默认两侧拼接,超过 4000 字会报错提示改用 notes_mode=a/b 取单侧。
glob 子集:*、?、**、[...]、{a,b};只接受工作区内相对路径,../ 形式直接报错。
典型场景
- 换机器接续:旧机
pack_handoff→ 把handoff.json拷到新机 → 新机migrate_handoff看漂移 →apply_handoff落地简报,模型读简报继续干。 - 目录改名或换盘符:
E:/work/proj变成F:/new/proj,简报里的路径自动改写,不必全文手找。 - 多工作区合并:把散在两个目录的同一件事收拢时,先对旧目录打包,在新目录迁移时会把「内容相同但路径不同」的文件识别为改名,避免重复劳动。
- 交付前状态留档:
apply_handoff产出的HANDOFF.md本身就是一份可交给同事或次日的自己的接续文档。 - 两台机器并行推进后收拢:各自
pack_handoff,回来diff_handoff看清谁的哪份文件更新、任务状态差在哪,再merge_handoff合成一份落地,避免手工比对。 - 跨工作区风险预估:
pack_handoff的文件清单 + 目标区migrate_handoff的漂移表,可以先看清「少了哪些、哪些被改过」再决定要不要接续。
安全边界
- 只写两个自有文件:
apply_handoff仅创建或覆盖out_dir下的HANDOFF.md与handoff.json,不删除、不修改清单之外的任何既有文件;migrate_handoff全程只读。 - 不越出工作区:
out_dir必须是目标工作区内的相对路径,绝对路径与含..段一律拒绝;glob 模式同样禁止越界。 - 不改文件内容:路径重映射只作用于 handoff 包内的状态文本,绝不写回源文件。
- 完整性优先拒绝:包被手工编辑或传输损坏时,
migrate_handoff与apply_handoff默认报错;确认可信再显式传strict: false(落地还需force: true),且结果里会标注校验失败。 - 体积有预算:
max_files上限 20000、max_hash_bytes上限 64 MB、bundle 文件上限 8 MB;超限报错或计入skipped_large,不会把大文件读进内存。 - 不含敏感兜底:
notes与文件清单会如实记录文本与相对路径。若状态描述里含密钥,请自行脱敏后再打包;需要批量脱敏可先用dsh-dotenv-toolkit的mask_env或dsh-credential-scan。 - 符号链接与特殊文件:遍历跳过符号链接(防环)与非普通文件,不跟随也不报错。
版本说明
v0.2.0:
- 新增
diff_handoff:两个 handoff 包的逐项对比(目标 / 决策 / 任务 / 备注 + 清单文件五态),一侧缺哈希时保守归入uncertain不误判;top控制明细截断 - 新增
merge_handoff:决策并集去重、任务并集(done_policy默认任一侧完成即完成)、清单按路径并集(file_policy默认较新侧为准)、notes 拼接超限显式报错;产物重算完整性并带merged溯源字段,可直接apply_handoff落地 stateOf归一化加固:外部手工包的decisions/open_tasks/journal非数组或含脏项时安全降级,diff/merge 不再抛错- 断言 160 → 280,
diff_handoff/merge_handoff同样经真实@deepseek-ai/dsh-tools包装层执行 happy path 与参数校验
v0.1.0(首个版本,四期插单):
pack_handoff/migrate_handoff/apply_handoff三个工具与handoff/v1包结构- 零依赖 glob 子集编译与遍历、sha256 指纹与规范化 JSON 完整性摘要、绝对路径前缀重映射、五态漂移检测、overwrite / skip / versioned 落地策略与 dry_run
- 与
dsh-workspace-journal的.journal约定兼容(可选带出近期条目)
160 条断言,经真实 @deepseek-ai/dsh-tools 包装层执行每个工具的 happy path 与参数校验。
RoadMap
- ~~v0.2:
diff_handoff两包对比 +merge_handoff合并~~ ✅ 已完成(0.2.0) - v0.3:状态自动提炼——从
.journal、todo 与最近改动的文件推断goal/open_tasks,把手填降为确认;支持include_context_preview带出关键文件前若干行,让简报脱离原目录也可读 - v0.4:真正的文件搬运——可选
copy_files把清单内文件按重映射后的路径复制过去(默认仍只出报告,保持只读安全线) - v0.5:与
dsh-mindvault打通——apply_handoff后可选把本次接续写成 raw 层溯源页,形成「一次迁移 = 一条可回溯记录」
不做的事:不读 dsh 会话历史(交给 dsh-session-exporter)、不做网络同步(本地文件操作)、不删除任何既有文件。
其他插件集成说明
dsh-session-exporter:那边搬「说了什么」(完整消息流水,多种格式导出),这边搬「干到哪儿了」(结构化状态 + 文件清单)。接续时建议先读这边的HANDOFF.md,需要回溯原话再查导出件。dsh-workspace-journal:pack_handoff的include_journal直接读它的.journal/YYYY-MM.md,把近期结论随包带走;包里的 journal 段落同样会被重映射。dsh-plugin-todo:任务清单可从 todo 取,写入open_tasks的{ text, done }形式,落地后变成HANDOFF.md里的复选框。dsh-mindvault:mindvault 管「知识与记忆页」的长期沉淀,本插件管「一次工作状态」的一次性搬运;handoff.json可作为 raw 层溯源凭证用mem_save归档。dsh-hash-checksum:清单里的sha256与它的输出口径一致(十六进制小写),可互验。dsh-file-search/dsh-folder-tree:漂移表出现dirty时,用它们定位缺失文件的去向。
FAQ
问:为什么不直接读会话历史,这样要手填 goal 太麻烦?
答:v0.1 刻意如此。不依赖宿主会话 API,插件在任何 harness 版本、任何工作区里行为一致,也不受会话结构变更影响;goal 一句话的成本远低于跨机器后发现导出格式对不上。自动从会话与 .journal 提炼状态已列入 RoadMap。
问:notes 里的路径只替换了来源根,其他绝对路径没改?
答:是的,这是设计取舍。插件只替换 source.root 前缀,不猜测其他绝对路径——误替换比漏替换危险得多。命中要求前缀之后紧跟分隔符或结束,所以 E:/work/proj-extra 不会被 E:/work/proj 带走。
问:verdict 是 renamed 是什么意思,能直接接续吗?
答:内容都在,只是路径变了(文件被改名或移动)。drift.moved 给了旧路径到新路径的对照表,按新路径读即可接续。
问:校验失败说摘要不符,但我确实改过 notes。
答:改过内容摘要必然变。确认无误后传 strict: false(apply_handoff 还需 force: true)放行,结果里的 integrity.ok 会保留 false 作为标注。
问:清单能包含二进制文件吗?
答:可以入清单(记大小与 sha256),但插件只搬清单不搬内容——它不会复制任何文件。需要把文件本体一起带走,请用 files 打清单后自行同步目录,或用 dsh-xlsx-lite、dsh-jsonl-stream 等针对具体类型处理。
问:diff_handoff 会把内容相同但路径不同的文件判成「改名」,merge_handoff 会怎么处理?
答:diff 按 sha256 互相认领,判为 moved 给出 from→to 对照;merge 则按路径并集——两个路径都会保留在合并包清单里(同一份内容各一条记录),落地后的 HANDOFF.md 清单会同时列出,由接续方自行取舍。这比强行猜一个「正确路径」安全。
问:为什么 .git、node_modules、.handoff 默认不进清单?
答:依赖可重装、产物可重建、.handoff 是本插件的输出,三者进清单只会造成噪声和自引用。需要改变范围时传 prune。
问:mode=versioned 会一直堆积版本文件吗?
答:每次递增 -v2、-v3……不覆盖旧文件,便于对比与回溯。想收敛就删掉旧版本,插件自身不做清理。
许可证
MIT
