dsh-workspace-handoff 0.1.0 → 0.2.0

package/README.md

@@ -10,14 +10,15 @@
 
 ## 功能说明
 
-
-三个工具：
+五个工具：
 
 | 工具 | 作用 | 关键能力 |
 |---|---|---|
 | `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`）：
 
@@ -31,6 +32,8 @@ handoff 包结构（`schema` 为 `handoff/v1`）：
 }
 ```
 
+经 `merge_handoff` 产出的包会多一个 `merged` 字段（两侧来源、较新侧、合并策略），经 `apply_handoff` 落地的包带 `migrated` 字段——两者可并存，便于溯源。
+
 设计要点：
 
 - **搬的是工作状态，不是消息流水**：`goal` / `decisions` / `open_tasks` 由模型自己声明，插件不读 dsh 会话历史，因此跨宿主、跨版本都能用，也不受会话导出格式变化影响。
@@ -108,8 +111,34 @@ await tools.apply_handoff({
 | `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` 收拢成一份：
+
+```javascript
+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}`；只接受工作区内相对路径，`../` 形式直接报错。
 
 ## 典型场景
@@ -119,6 +148,7 @@ glob 子集：`*`、`?`、`**`、`[...]`、`{a,b}`；只接受工作区内相对
 - **目录改名或换盘符**：`E:/work/proj` 变成 `F:/new/proj`，简报里的路径自动改写，不必全文手找。
 - **多工作区合并**：把散在两个目录的同一件事收拢时，先对旧目录打包，在新目录迁移时会把「内容相同但路径不同」的文件识别为改名，避免重复劳动。
 - **交付前状态留档**：`apply_handoff` 产出的 `HANDOFF.md` 本身就是一份可交给同事或次日的自己的接续文档。
+- **两台机器并行推进后收拢**：各自 `pack_handoff`，回来 `diff_handoff` 看清谁的哪份文件更新、任务状态差在哪，再 `merge_handoff` 合成一份落地，避免手工比对。
 - **跨工作区风险预估**：`pack_handoff` 的文件清单 + 目标区 `migrate_handoff` 的漂移表，可以先看清「少了哪些、哪些被改过」再决定要不要接续。
 
 ## 安全边界
@@ -134,6 +164,12 @@ glob 子集：`*`、`?`、`**`、`[...]`、`{a,b}`；只接受工作区内相对
 
 ## 版本说明
 
+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（首个版本，四期插单）：
 
@@ -146,7 +182,7 @@ v0.1.0（首个版本，四期插单）：
 ## RoadMap
 
 
-- **v0.2**：`diff_handoff`——两个 handoff 包对比（同一件事在不同机器上各自推进后谁新、状态差异在哪），以及 `merge_handoff` 合并两份任务清单
+- ~~**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 层溯源页，形成「一次迁移 = 一条可回溯记录」
@@ -181,6 +217,9 @@ v0.1.0（首个版本，四期插单）：
 **问：清单能包含二进制文件吗？**
 答：可以入清单（记大小与 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`。
 

package/index.js

@@ -1,10 +1,12 @@
 /*
  * dsh-workspace-handoff —— 工作区会话迁移插件（零运行时依赖、确定性）。
  *
- * 三个工具：
+ * 五个工具：
  *  - pack_handoff    采集当前工作区的一次「工作状态」：目标 / 关键决策 / 未完成任务 / 备注 + 上下文文件清单（glob 展开、sha256 指纹），打成可迁移 handoff 包
  *  - migrate_handoff 把 handoff 包迁移到另一个工作区根：文本内绝对路径重映射 + 漂移检测（未变/已改/改名/缺失/新增），只出报告不落盘
  *  - apply_handoff   在目标工作区落地 HANDOFF.md + handoff.json（覆盖/跳过/版本化三种冲突策略，支持 dry-run，永不删除任何文件）
+ *  - diff_handoff    对比两个 handoff 包（v0.2）：目标/决策/任务/清单文件逐项差异，只读不落盘
+ *  - merge_handoff   合并两个 handoff 包为一个新包（v0.2）：决策并集、任务并集（done 优先）、清单按新者为准，产物可直接交给 apply_handoff
  *
  * 口径（v0.1，README 详述）：
  *  - 会话「内容」由模型自己声明（goal/decisions/open_tasks/notes）——本插件不读 dsh 会话历史，
@@ -22,7 +24,8 @@ export const name = "dsh-workspace-handoff"
 export const inject = ["tools"]
 
 const SCHEMA = "handoff/v1"
-const PLUGIN_VERSION = "0.1.0"
+const PLUGIN_VERSION = "0.2.0"
+const MAX_NOTES = 4000
 const DEFAULT_MAX_FILES = 2000
 const HARD_MAX_FILES = 20000
 const DEFAULT_MAX_HASH_BYTES = 4 * 1024 * 1024
@@ -865,6 +868,329 @@ export function applyHandoff(args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// diff_handoff / merge_handoff（v0.2）
+// ---------------------------------------------------------------------------
+
+function capList(arr, top) {
+  return { total: arr.length, items: arr.slice(0, top) }
+}
+
+function bundleTime(b) {
+  const t = Date.parse(b.created_at || "")
+  return Number.isFinite(t) ? t : 0
+}
+
+function fileList(b) {
+  return (b.context && Array.isArray(b.context.files) ? b.context.files : []).filter((f) => f && typeof f.path === "string")
+}
+
+function stateOf(b) {
+  const st = b.state || {}
+  return {
+    goal: typeof st.goal === "string" ? st.goal : "",
+    decisions: strArr(st.decisions),
+    open_tasks: taskArr(st.open_tasks),
+    notes: typeof st.notes === "string" ? st.notes : "",
+    journal: journalArr(st.journal),
+  }
+}
+
+function arrOf(x) {
+  return Array.isArray(x) ? x : []
+}
+
+function strArr(x) {
+  return arrOf(x).filter((v) => typeof v === "string" && v.trim() !== "").map((v) => v.trim())
+}
+
+function taskArr(x) {
+  return arrOf(x)
+    .filter((t) => t && typeof t === "object" && typeof t.text === "string" && t.text.trim() !== "")
+    .map((t) => ({ text: t.text.trim(), done: Boolean(t.done) }))
+}
+
+function journalArr(x) {
+  return arrOf(x).filter((j) => j && typeof j === "object")
+}
+
+function choice(value, allowed, label) {
+  const v = value === undefined || value === null || value === "" ? undefined : String(value)
+  if (v === undefined) return undefined
+  if (!allowed.includes(v)) throw new Error(`${label} 只能是 ${allowed.join(" / ")}（收到 ${v}）`)
+  return v
+}
+
+/**
+ * 对比两个 handoff 包（只读不落盘）：目标/决策/任务/备注逐项差异 + 清单文件五态
+ * （same / content_changed / moved / only_a / only_b；一方缺哈希时归 uncertain 保守列出）。
+ * 改名识别：某侧独有的路径，若内容能在另一侧独有路径中找到同 sha256 则判 moved，一份内容只认领一次。
+ */
+export function diffHandoff(args) {
+  const a = parseBundle(args.a_bundle, process.cwd())
+  const b = parseBundle(args.b_bundle, process.cwd())
+  const strict = args.strict === undefined ? true : Boolean(args.strict)
+  const ia = verifyIntegrity(a)
+  const ib = verifyIntegrity(b)
+  if (strict && (!ia.ok || !ib.ok)) {
+    const who = !ia.ok && !ib.ok ? "a/b 两侧" : !ia.ok ? "a 侧" : "b 侧"
+    throw new Error(`bundle 完整性校验失败（${who}）。确认是对比手工编辑过的包可传 strict=false 放行并标注`)
+  }
+  const top = clampNumber(args.top, TOP_DEFAULT, 1, TOP_CAP, "top")
+
+  const sa = stateOf(a)
+  const sb = stateOf(b)
+
+  const decisions = {
+    common: sb.decisions.filter((d) => new Set(sa.decisions).has(d)).length,
+    only_a: sa.decisions.filter((d) => !new Set(sb.decisions).has(d)),
+    only_b: sb.decisions.filter((d) => !new Set(sa.decisions).has(d)),
+  }
+
+  const mapA = new Map(sa.open_tasks.map((t) => [t.text, t]))
+  const mapB = new Map(sb.open_tasks.map((t) => [t.text, t]))
+  const tasks = { in_both: 0, only_a: [], only_b: [], status_changed: [] }
+  for (const [text, ta] of mapA) {
+    const tb = mapB.get(text)
+    if (!tb) tasks.only_a.push({ text, done: ta.done })
+    else {
+      tasks.in_both++
+      if (ta.done !== tb.done) tasks.status_changed.push({ text, a_done: ta.done, b_done: tb.done })
+    }
+  }
+  for (const [text, tb] of mapB) if (!mapA.has(text)) tasks.only_b.push({ text, done: tb.done })
+
+  const journalKey = (j) => `${j && j.time ? j.time : ""}|${j && j.body ? j.body : ""}`
+  const jA = new Set(sa.journal.map(journalKey))
+  const jB = new Set(sb.journal.map(journalKey))
+  const journal = {
+    a_count: sa.journal.length,
+    b_count: sb.journal.length,
+    common: [...jA].filter((k) => jB.has(k)).length,
+    only_a: [...jA].filter((k) => !jB.has(k)).length,
+    only_b: [...jB].filter((k) => !jA.has(k)).length,
+  }
+
+  const fa = fileList(a)
+  const fb = fileList(b)
+  const pa = new Map(fa.map((f) => [f.path, f]))
+  const pb = new Map(fb.map((f) => [f.path, f]))
+  const files = { same: [], content_changed: [], moved: [], only_a: [], only_b: [], uncertain: [] }
+  const aOnly = fa.filter((f) => !pb.has(f.path))
+  const bOnly = fb.filter((f) => !pa.has(f.path))
+  const bClaimed = new Set()
+
+  for (const f of fa) {
+    const g = pb.get(f.path)
+    if (!g) continue
+    if (f.sha256 && g.sha256) {
+      if (f.sha256 === g.sha256) files.same.push({ path: f.path, sha256: f.sha256 })
+      else files.content_changed.push({ path: f.path, a_sha256: f.sha256.slice(0, 12), b_sha256: g.sha256.slice(0, 12), a_size: f.size, b_size: g.size })
+    } else if (!f.sha256 && !g.sha256) {
+      if (f.size === g.size) files.same.push({ path: f.path, by: "size（两侧均未记录哈希）" })
+      else files.content_changed.push({ path: f.path, reason: "size 不符（两侧均未记录哈希）", a_size: f.size, b_size: g.size })
+    } else {
+      files.uncertain.push({ path: f.path, reason: "一侧未记录 sha256，无法判内容异同", a_size: f.size, b_size: g.size })
+    }
+  }
+
+  const bOnlyByDigest = new Map()
+  for (const f of bOnly) if (f.sha256 && !bOnlyByDigest.has(f.sha256)) bOnlyByDigest.set(f.sha256, f)
+  for (const f of aOnly) {
+    const hit = f.sha256 ? bOnlyByDigest.get(f.sha256) : null
+    if (hit && !bClaimed.has(hit.path)) {
+      bClaimed.add(hit.path)
+      files.moved.push({ from: f.path, to: hit.path, sha256: f.sha256 })
+    } else files.only_a.push({ path: f.path, size: f.size })
+  }
+  for (const f of bOnly) if (!bClaimed.has(f.path)) files.only_b.push({ path: f.path, size: f.size })
+
+  const stateDiff =
+    (sa.goal === sb.goal ? 0 : 1) +
+    (sa.notes === sb.notes ? 0 : 1) +
+    decisions.only_a.length +
+    decisions.only_b.length +
+    tasks.only_a.length +
+    tasks.only_b.length +
+    tasks.status_changed.length
+  const filesDiff =
+    files.content_changed.length + files.moved.length + files.only_a.length + files.only_b.length + files.uncertain.length
+
+  let verdict, verdict_note
+  if (stateDiff === 0 && filesDiff === 0) {
+    verdict = "identical"
+    verdict_note = "两包状态与清单完全一致，无需合并"
+  } else if (filesDiff === 0) {
+    verdict = "state_diverged"
+    verdict_note = `清单一致，状态有 ${stateDiff} 处差异，可按 merge_handoff 取并集`
+  } else if (stateDiff === 0) {
+    verdict = "files_diverged"
+    verdict_note = `状态一致，清单有 ${filesDiff} 处差异`
+  } else {
+    verdict = "diverged"
+    verdict_note = `状态 ${stateDiff} 处、清单 ${filesDiff} 处差异，merge 前先看清哪侧为准`
+  }
+
+  const at = bundleTime(a)
+  const bt = bundleTime(b)
+
+  return {
+    schema: SCHEMA,
+    compared: {
+      a: { label: a.source.label, root: normSlashes(a.source.root), created_at: a.created_at, files: fa.length, version: a.producer && a.producer.version },
+      b: { label: b.source.label, root: normSlashes(b.source.root), created_at: b.created_at, files: fb.length, version: b.producer && b.producer.version },
+      newer: at === bt ? "same" : bt > at ? "b" : "a",
+    },
+    integrity: { a: ia, b: ib },
+    state: {
+      goal: { same: sa.goal === sb.goal, a: sa.goal, b: sb.goal },
+      notes: { same: sa.notes === sb.notes, a_length: sa.notes.length, b_length: sb.notes.length },
+      decisions: { common: decisions.common, only_a: capList(decisions.only_a, top), only_b: capList(decisions.only_b, top) },
+      open_tasks: {
+        in_both: tasks.in_both,
+        status_changed: capList(tasks.status_changed, top),
+        only_a: capList(tasks.only_a, top),
+        only_b: capList(tasks.only_b, top),
+      },
+      journal,
+    },
+    files: {
+      same: capList(files.same, top),
+      content_changed: capList(files.content_changed, top),
+      moved: capList(files.moved, top),
+      only_a: capList(files.only_a, top),
+      only_b: capList(files.only_b, top),
+      uncertain: capList(files.uncertain, top),
+    },
+    counts: { state_diff: stateDiff, files_diff: filesDiff },
+    verdict,
+    verdict_note,
+  }
+}
+
+/**
+ * 合并两个 handoff 包为一个新包（纯内存、不落盘，产物可直接交给 apply_handoff 落地）：
+ *  - goal 默认取较新一侧（可 goal_from=a/b）
+ *  - decisions 取并集去重（a 在前、b 补新）
+ *  - open_tasks 按文本并集，同一条任一侧 done 即视为完成（可 done_policy=a/b 按单侧为准）
+ *  - notes 默认两侧拼接（超 4000 字需改用 notes_mode 取单侧）
+ *  - files 按路径并集，同路径默认以较新一侧条目为准（可 file_policy=a/b）
+ *  - patterns 并集；合并来源与策略写入包内 merged 字段，integrity 重算
+ */
+export function mergeHandoff(args) {
+  const a = parseBundle(args.a_bundle, process.cwd())
+  const b = parseBundle(args.b_bundle, process.cwd())
+  const strict = args.strict === undefined ? true : Boolean(args.strict)
+  const ia = verifyIntegrity(a)
+  const ib = verifyIntegrity(b)
+  if (strict && (!ia.ok || !ib.ok)) {
+    const who = !ia.ok && !ib.ok ? "a/b 两侧" : !ia.ok ? "a 侧" : "b 侧"
+    throw new Error(`bundle 完整性校验失败（${who}）。确认无误可传 strict=false 放行（合并包会标注 integrity 不可信）`)
+  }
+
+  const goalFrom = choice(args.goal_from, ["newer", "a", "b"], "goal_from") || "newer"
+  const notesMode = choice(args.notes_mode, ["both", "a", "b"], "notes_mode") || "both"
+  const filePolicy = choice(args.file_policy, ["newer", "a", "b"], "file_policy") || "newer"
+  const donePolicy = choice(args.done_policy, ["any_done", "a", "b"], "done_policy") || "any_done"
+
+  const at = bundleTime(a)
+  const bt = bundleTime(b)
+  const newer = bt > at ? "b" : "a"
+  const goalPick = goalFrom === "newer" ? newer : goalFrom
+  const filePick = filePolicy === "newer" ? newer : filePolicy
+
+  const sa = stateOf(a)
+  const sb = stateOf(b)
+
+  const goal = (goalPick === "a" ? sa.goal : sb.goal).trim()
+  if (goal === "") throw new Error(`合并后 goal 为空（${goalPick === "a" ? "a" : "b"} 侧缺少 state.goal）`)
+  if (goal.length > 500) throw new Error("goal 长度不得超过 500 字符")
+
+  const decisions = []
+  for (const d of [...sa.decisions, ...sb.decisions]) if (!decisions.includes(d)) decisions.push(d)
+
+  const taskA = new Map(sa.open_tasks.map((t) => [t.text, Boolean(t.done)]))
+  const taskB = new Map(sb.open_tasks.map((t) => [t.text, Boolean(t.done)]))
+  const open_tasks = []
+  for (const text of [...taskA.keys(), ...[...taskB.keys()].filter((x) => !taskA.has(x))]) {
+    const ha = taskA.has(text)
+    const hb = taskB.has(text)
+    let done
+    if (donePolicy === "a") done = ha ? taskA.get(text) : Boolean(taskB.get(text))
+    else if (donePolicy === "b") done = hb ? taskB.get(text) : Boolean(taskA.get(text))
+    else done = Boolean(taskA.get(text)) || Boolean(taskB.get(text))
+    open_tasks.push({ text, done })
+  }
+
+  let notes
+  if (notesMode === "a") notes = sa.notes
+  else if (notesMode === "b") notes = sb.notes
+  else notes = sa.notes && sb.notes ? `${sa.notes}\n\n${sb.notes}` : sa.notes || sb.notes
+  if (notes.length > MAX_NOTES) throw new Error(`合并后 notes 超过 ${MAX_NOTES} 字符（实际 ${notes.length}），请改用 notes_mode=a 或 b 取单侧`)
+
+  const jMap = new Map()
+  for (const j of [...sa.journal, ...sb.journal]) {
+    const key = `${j && j.time ? j.time : ""}|${j && j.body ? j.body : ""}`
+    if (j && j.body && !jMap.has(key)) jMap.set(key, j)
+  }
+  const jLimit = clampNumber(args.journal_limit, 50, 1, 200, "journal_limit")
+  const journal = [...jMap.values()].sort((x, y) => String(y.time || "").localeCompare(String(x.time || ""))).slice(0, jLimit)
+
+  const fa = fileList(a)
+  const fb = fileList(b)
+  const mergedFiles = new Map()
+  const secondary = filePick === "a" ? fb : fa
+  const primary = filePick === "a" ? fa : fb
+  for (const f of secondary) mergedFiles.set(f.path, f)
+  for (const f of primary) mergedFiles.set(f.path, f)
+  const files = [...mergedFiles.values()].sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0))
+
+  const patterns = []
+  for (const p of [...strArr(a.context.patterns), ...strArr(b.context.patterns)]) if (!patterns.includes(p)) patterns.push(p)
+
+  const saStats = a.context.stats || {}
+  const sbStats = b.context.stats || {}
+  const label = args.label === undefined || String(args.label).trim() === ""
+    ? `${(a.source.label || "a")}+${(b.source.label || "b")}`
+    : String(args.label).trim()
+  const primaryBundle = filePick === "a" ? a : b
+
+  const bundle = {
+    schema: SCHEMA,
+    kind: "handoff",
+    created_at: new Date().toISOString(),
+    producer: { plugin: name, version: PLUGIN_VERSION },
+    source: {
+      root: normSlashes(primaryBundle.source.root),
+      platform: primaryBundle.source.platform || process.platform,
+      label,
+    },
+    state: { goal, decisions, open_tasks, notes },
+    context: {
+      patterns,
+      files,
+      stats: {
+        matched: files.length,
+        scanned: (Number(saStats.scanned) || 0) + (Number(sbStats.scanned) || 0),
+        skipped_large: (Number(saStats.skipped_large) || 0) + (Number(sbStats.skipped_large) || 0),
+        hashed: files.length > 0 && files.every((f) => typeof f.sha256 === "string"),
+      },
+    },
+    merged: {
+      a: { label: a.source.label, root: normSlashes(a.source.root), created_at: a.created_at, files: fa.length, integrity_ok: ia.ok },
+      b: { label: b.source.label, root: normSlashes(b.source.root), created_at: b.created_at, files: fb.length, integrity_ok: ib.ok },
+      newer,
+      policies: { goal_from: goalFrom, notes_mode: notesMode, file_policy: filePolicy, done_policy: donePolicy },
+    },
+  }
+  if (journal.length > 0) bundle.state.journal = journal
+
+  const body = { ...bundle }
+  delete body.integrity
+  bundle.integrity = { algo: "sha256-canonical-v1", digest: sha256Text(canonicalize(body)) }
+  return bundle
+}
+
 // ---------------------------------------------------------------------------
 // 工具定义
 // ---------------------------------------------------------------------------
@@ -919,6 +1245,52 @@ const migrateHandoffTool = defineTool({
   },
 })
 
+const diffHandoffTool = defineTool({
+  name: "diff_handoff",
+  description:
+    "对比两个 handoff 包（只读不落盘）：目标/备注/关键决策/任务清单逐项差异，上下文文件按五态对比"
+    +"（相同 / 内容已变 / 改名移动 / 仅 a 有 / 仅 b 有；缺哈希时保守归入 uncertain），并给出结论"
+    +" identical / state_diverged / files_diverged / diverged。适合比较同一工作区两次 pack 或两个分支的接续包。",
+  parameters: {
+    a_bundle: { type: "string", description: "必填，第一份 handoff 包：JSON 字符串或文件路径（如 .handoff/handoff.json）" },
+    b_bundle: { type: "string", description: "必填，第二份 handoff 包：JSON 字符串或文件路径" },
+    strict: { type: "boolean", description: "可选，任一侧完整性校验失败时是否直接报错（默认 true）" },
+    top: { type: "number", description: "可选，各类明细最多列出条数（1~500，默认 50）" },
+  },
+  output: { schema: { type: "string" }, render: (_a, v) => [{ type: "text", text: v }] },
+  async execute(args) {
+    if (!args || args.a_bundle === undefined) throw new Error("缺少必填参数 a_bundle")
+    if (!args || args.b_bundle === undefined) throw new Error("缺少必填参数 b_bundle")
+    return JSON.stringify(diffHandoff(args), null, 2)
+  },
+})
+
+const mergeHandoffTool = defineTool({
+  name: "merge_handoff",
+  description:
+    "合并两个 handoff 包为一个新包（纯内存不落盘，产物可直接交给 apply_handoff 落地或继续 diff）："
+    +"关键决策取并集去重；任务按文本并集、同一条任一侧完成即视为完成（done_policy 可改）；"
+    +"清单文件按路径并集、同路径默认以较新一侧为准（file_policy 可改）；notes 默认两侧拼接。"
+    +"合并来源与策略写入包内 merged 字段，完整性摘要重算。",
+  parameters: {
+    a_bundle: { type: "string", description: "必填，第一份 handoff 包：JSON 字符串或文件路径" },
+    b_bundle: { type: "string", description: "必填，第二份 handoff 包：JSON 字符串或文件路径" },
+    goal_from: { type: "string", description: "可选，合并后 goal 取哪侧：newer（默认，按 created_at）/ a / b" },
+    notes_mode: { type: "string", description: "可选，备注取法：both（默认拼接，超 4000 字需改用单侧）/ a / b" },
+    file_policy: { type: "string", description: "可选，清单同路径冲突以哪侧为准：newer（默认）/ a / b" },
+    done_policy: { type: "string", description: "可选，任务完成状态取法：any_done（默认任一侧完成即完成）/ a / b" },
+    label: { type: "string", description: "可选，合并包的工作区标注（默认 a+b 两侧 label 拼接）" },
+    journal_limit: { type: "number", description: "可选，合并后 journal 条目上限（1~200，默认 50）" },
+    strict: { type: "boolean", description: "可选，任一侧完整性校验失败时是否直接报错（默认 true）" },
+  },
+  output: { schema: { type: "string" }, render: (_a, v) => [{ type: "text", text: v }] },
+  async execute(args) {
+    if (!args || args.a_bundle === undefined) throw new Error("缺少必填参数 a_bundle")
+    if (!args || args.b_bundle === undefined) throw new Error("缺少必填参数 b_bundle")
+    return JSON.stringify(mergeHandoff(args), null, 2)
+  },
+})
+
 const applyHandoffTool = defineTool({
   name: "apply_handoff",
   description:
@@ -952,6 +1324,8 @@ export function apply(ctx) {
   ctx.tools.register(packHandoffTool)
   ctx.tools.register(migrateHandoffTool)
   ctx.tools.register(applyHandoffTool)
+  ctx.tools.register(diffHandoffTool)
+  ctx.tools.register(mergeHandoffTool)
 }
 
-export { packHandoffTool, migrateHandoffTool, applyHandoffTool }
+export { packHandoffTool, migrateHandoffTool, applyHandoffTool, diffHandoffTool, mergeHandoffTool }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-workspace-handoff",
-  "version": "0.1.0",
-  "description": "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 root with absolute-path remapping and drift detection (unchanged/changed/moved/missing/extra), and apply it as HANDOFF.md + handoff.json with overwrite/skip/versioned conflict modes and dry-run. Zero dependencies, Node built-ins only, never deletes files.",
+  "version": "0.2.0",
+  "description": "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 root with absolute-path remapping and drift detection (unchanged/changed/moved/missing/extra), apply it as HANDOFF.md + handoff.json with overwrite/skip/versioned conflict modes and dry-run, and since v0.2 diff two bundles (state + five-way file comparison) or merge them into a new bundle (decision/task union, file union with newer-wins policy). Zero dependencies, Node built-ins only, never deletes files.",
   "type": "module",
   "main": "index.js",
   "files": [