dsh-workspace-handoff 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# dsh-workspace-handoff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+工作区会话迁移插件（零运行时依赖，仅 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 只看计划；落地包重算完整性并记录迁移溯源 |
+
+handoff 包结构（`schema` 为 `handoff/v1`）：
+
+```text
+{
+  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 }
+}
+```
+
+设计要点：
+
+- **搬的是工作状态，不是消息流水**：`goal` / `decisions` / `open_tasks` 由模型自己声明，插件不读 dsh 会话历史，因此跨宿主、跨版本都能用，也不受会话导出格式变化影响。
+- **清单只记相对路径**（统一 `/` 分隔）：这是换机器、换盘符仍可解的前提；绝对路径只出现在 `source.root` 与文本描述里，迁移时按前缀重映射。
+- **完整性可验**：对不含 `integrity` 的包做键升序规范化 JSON 后取 sha256；字段乱序不影响摘要，手工改内容会被检出。
+
+## 安装
+
+
+```bash
+npm install dsh-workspace-handoff
+```
+
+本地开发调试（Debug patch）：新建 debug.patch.yml
+
+```yaml
+- insert:
+    - id: workspace-handoff
+      name: "E:/dsh-plugins/dsh-workspace-handoff/index.js"
+```
+
+## 使用说明
+
+
+### 1. 在来源工作区打包
+
+```javascript
+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. 在目标工作区迁移
+
+```javascript
+const report = await tools.migrate_handoff({
+  bundle,                    // JSON 字符串，或 handoff.json 的路径
+  target_root: "F:/new-machine/arch-notes",
+})
+```
+
+关注 `verdict`：
+
+- `clean` 清单文件全部一致，可直接接续
+- `renamed` 内容都在、只是路径改了（改名或移动），按 `drift.moved` 里的新路径读
+- `dirty` 有缺失或内容变更，接续前先确认原因
+
+### 3. 落地接续简报
+
+```javascript
+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 | 见上 |
+| `max_files` / `max_hash_bytes` / `journal_limit` / `top` | number | 预算类参数，越界或传字符串会被拒 |
+
+glob 子集：`*`、`?`、`**`、`[...]`、`{a,b}`；只接受工作区内相对路径，`../` 形式直接报错。
+
+## 典型场景
+
+
+- **换机器接续**：旧机 `pack_handoff` → 把 `handoff.json` 拷到新机 → 新机 `migrate_handoff` 看漂移 → `apply_handoff` 落地简报，模型读简报继续干。
+- **目录改名或换盘符**：`E:/work/proj` 变成 `F:/new/proj`，简报里的路径自动改写，不必全文手找。
+- **多工作区合并**：把散在两个目录的同一件事收拢时，先对旧目录打包，在新目录迁移时会把「内容相同但路径不同」的文件识别为改名，避免重复劳动。
+- **交付前状态留档**：`apply_handoff` 产出的 `HANDOFF.md` 本身就是一份可交给同事或次日的自己的接续文档。
+- **跨工作区风险预估**：`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.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`——两个 handoff 包对比（同一件事在不同机器上各自推进后谁新、状态差异在哪），以及 `merge_handoff` 合并两份任务清单
+- **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` 等针对具体类型处理。
+
+**问：为什么 `.git`、`node_modules`、`.handoff` 默认不进清单？**
+答：依赖可重装、产物可重建、`.handoff` 是本插件的输出，三者进清单只会造成噪声和自引用。需要改变范围时传 `prune`。
+
+**问：`mode=versioned` 会一直堆积版本文件吗？**
+答：每次递增 `-v2`、`-v3`……不覆盖旧文件，便于对比与回溯。想收敛就删掉旧版本，插件自身不做清理。
+
+## 许可证
+
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: workspace-handoff
+      name: "dsh-workspace-handoff"

package/index.js

@@ -0,0 +1,957 @@
+/*
+ * dsh-workspace-handoff —— 工作区会话迁移插件（零运行时依赖、确定性）。
+ *
+ * 三个工具：
+ *  - pack_handoff    采集当前工作区的一次「工作状态」：目标 / 关键决策 / 未完成任务 / 备注 + 上下文文件清单（glob 展开、sha256 指纹），打成可迁移 handoff 包
+ *  - migrate_handoff 把 handoff 包迁移到另一个工作区根：文本内绝对路径重映射 + 漂移检测（未变/已改/改名/缺失/新增），只出报告不落盘
+ *  - apply_handoff   在目标工作区落地 HANDOFF.md + handoff.json（覆盖/跳过/版本化三种冲突策略，支持 dry-run，永不删除任何文件）
+ *
+ * 口径（v0.1，README 详述）：
+ *  - 会话「内容」由模型自己声明（goal/decisions/open_tasks/notes）——本插件不读 dsh 会话历史，
+ *    与 dsh-session-exporter（导出消息流水）分工：那边搬「说了什么」，这边搬「干到哪儿了」
+ *  - 清单里一律记相对路径（统一 "/" 分隔），因此换机器、换盘符、换目录名都可解
+ *  - 文本重映射只替换来源根前缀，不猜测其他绝对路径；Windows 盘符路径比对大小写不敏感
+ *  - 完整性 = 对不含 integrity 字段的 bundle 做规范化 JSON 后取 sha256，迁移与应用时校验
+ */
+import { defineTool } from "@deepseek-ai/dsh-tools"
+import fs from "node:fs"
+import path from "node:path"
+import crypto from "node:crypto"
+
+export const name = "dsh-workspace-handoff"
+export const inject = ["tools"]
+
+const SCHEMA = "handoff/v1"
+const PLUGIN_VERSION = "0.1.0"
+const DEFAULT_MAX_FILES = 2000
+const HARD_MAX_FILES = 20000
+const DEFAULT_MAX_HASH_BYTES = 4 * 1024 * 1024
+const HARD_MAX_HASH_BYTES = 64 * 1024 * 1024
+const DEFAULT_PRUNE = [".git", "node_modules", ".handoff", ".journal", "dist", "build", "__pycache__"]
+const BUNDLE_MAX_BYTES = 8 * 1024 * 1024
+const TOP_DEFAULT = 50
+const TOP_CAP = 500
+
+// ---------------------------------------------------------------------------
+// 路径基础
+// ---------------------------------------------------------------------------
+
+/** 统一分隔符为 "/"，去掉重复分隔符与尾部分隔符（盘符 "C:/x" 形式保留） */
+export function normSlashes(p) {
+  return String(p).replace(/[\\/]+/g, "/").replace(/\/+$/, "") || "/"
+}
+
+/** 根目录解析：相对路径按 cwd 展开，~ 归.home 展开，返回绝对路径 */
+export function resolveRoot(root) {
+  if (typeof root !== "string" || root.trim() === "") throw new Error("root 必须为非空字符串")
+  const p = root.trim()
+  return path.resolve(p.startsWith("~") ? process.env.HOME || process.env.USERPROFILE || p : p)
+}
+
+/** 判断 abs 是否位于 root 内（含 root 自身）；Windows 盘符路径大小写不敏感 */
+export function isWithin(root, abs) {
+  const r = normSlashes(root).toLowerCase()
+  const a = normSlashes(abs).toLowerCase()
+  return a === r || a.startsWith(r + "/")
+}
+
+function isWinStyle(p) {
+  return /^[A-Za-z]:[\\/]/.test(p) || /^\\\\/.test(p)
+}
+
+/**
+ * 文本内绝对路径重映射：只替换 sourceRoot 前缀（容忍 / 与反斜杠混用、Windows 大小写差异），
+ * 保留前缀之后原有的分隔符；后面紧跟路径字符时不算命中（防 dsh-plugins-extra 被误替换）。
+ * 返回 { text, count }
+ */
+export function remapText(text, sourceRoot, targetRoot) {
+  if (typeof text !== "string" || text === "") return { text, count: 0 }
+  const src = normSlashes(sourceRoot)
+  const segs = src.split("/").filter((s) => s !== "")
+  if (segs.length === 0) return { text, count: 0 }
+  let pattern = segs.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[\\\\/]")
+  if (src.startsWith("/")) pattern = "/" + pattern
+  const flags = isWinStyle(src) || isWinStyle(targetRoot) ? "gi" : "g"
+  const re = new RegExp(pattern + "(?![\\w.\\-])", flags)
+  let count = 0
+  const out = text.replace(re, () => {
+    count++
+    return targetRoot
+  })
+  return { text: out, count }
+}
+
+// ---------------------------------------------------------------------------
+// glob（零依赖子集：** / * / ? / [...] / {a,b}）
+// ---------------------------------------------------------------------------
+
+const MAGIC_RE = /[*?[\]{}]/
+
+/** 编译单个路径段为正则片段：* 匹配非斜杠任意；? 匹配非斜杠单字；[...] 原样；{a,b} 转分支 */
+function compileSegment(seg) {
+  let out = ""
+  let i = 0
+  while (i < seg.length) {
+    const ch = seg[i]
+    if (ch === "*") {
+      out += "[^/]*"
+      i++
+    } else if (ch === "?") {
+      out += "[^/]"
+      i++
+    } else if (ch === "{") {
+      const close = seg.indexOf("}", i)
+      if (close === -1) {
+        out += "\\{"
+        i++
+        continue
+      }
+      const opts = seg.slice(i + 1, close).split(",").filter((o) => o !== "")
+      if (opts.length === 0) {
+        out += "\\{\\}"
+        i = close + 1
+        continue
+      }
+      out +=
+        "(?:" +
+        opts.map((o) => o.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/([^\\])\*/g, "$1[^/]*")).join("|") +
+        ")"
+      i = close + 1
+    } else if (ch === "[") {
+      const close = seg.indexOf("]", i + 1)
+      if (close === -1) {
+        out += "\\["
+        i++
+        continue
+      }
+      let cls = seg.slice(i, close + 1)
+      if (cls[1] === "!") cls = "[^" + cls.slice(2)
+      out += cls
+      i = close + 1
+    } else {
+      out += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+      i++
+    }
+  }
+  return out
+}
+
+/**
+ * 编译 glob 为正则（锚定整串，仅匹配以 "/" 分隔的相对路径）：
+ *  - 末段 ** → 该目录下任意深度至少一层（src 加双星 匹配 src/a、src/a/b，不匹配 src 本身）
+ *  - 中间双星 → 任意段数（含零段）：a + 双星 + b 匹配 a/b 与 a/x/y/b
+ */
+export function compileGlob(pattern) {
+  if (typeof pattern !== "string" || pattern.trim() === "") throw new Error("glob 必须为非空字符串")
+  const p = normSlashes(pattern).replace(/^\.\//, "")
+  const parts = p.split("/").filter((s) => s !== "")
+  if (parts.length === 0) throw new Error(`glob "${pattern}" 为空`)
+  let re = "^"
+  parts.forEach((seg, idx) => {
+    const last = idx === parts.length - 1
+    if (seg === "**") {
+      re += last ? ".+$" : "(?:[^/]+/)*"
+      return
+    }
+    re += compileSegment(seg)
+    if (!last) re += "/"
+  })
+  re += "$"
+  return new RegExp(re)
+}
+
+export function matchGlob(pattern, relPath) {
+  return compileGlob(pattern).test(normSlashes(relPath))
+}
+
+/** 遍历 + 匹配：一次 readdir 走到底，跳过符号链接防环，命中数受 max_files 预算约束 */
+export function walkWorkspace(root, patterns, opts = {}) {
+  const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES
+  const prune = (opts.prune ?? DEFAULT_PRUNE).map((p) => normSlashes(p).replace(/\/+$/, ""))
+  const dirs = []
+  const direct = []
+  for (const raw of patterns) {
+    if (typeof raw !== "string" || raw.trim() === "") throw new Error("glob 模式必须为非空字符串")
+    const p = normSlashes(raw).replace(/^\.\//, "")
+    if (p.startsWith("../") || p === ".." || p.startsWith("/")) {
+      throw new Error(`glob 模式 "${raw}" 越出工作区范围（只允许相对路径）`)
+    }
+    if (MAGIC_RE.test(p)) dirs.push({ pattern: p, re: compileGlob(p) })
+    else direct.push(p)
+  }
+
+  const found = new Map()
+  let scanned = 0
+
+  for (const d of direct) {
+    const abs = path.resolve(root, d.split("/").join(path.sep))
+    if (!fs.existsSync(abs)) continue
+    const st = fs.statSync(abs)
+    if (!st.isFile()) continue
+    found.set(d, { size: st.size, mtimeMs: Math.floor(st.mtimeMs) })
+  }
+
+  if (dirs.length > 0) {
+    const stack = [root]
+    while (stack.length > 0) {
+      const cur = stack.pop()
+      let ents
+      try {
+        ents = fs.readdirSync(cur, { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const ent of ents) {
+        const abs = path.join(cur, ent.name)
+        const rel = normSlashes(path.relative(root, abs))
+        if (ent.isSymbolicLink()) continue
+        if (ent.isDirectory()) {
+          if (prune.some((p) => rel === p || rel.startsWith(p + "/"))) continue
+          stack.push(abs)
+          continue
+        }
+        if (!ent.isFile()) continue
+        scanned++
+        if (!dirs.some((g) => g.re.test(rel))) continue
+        if (found.has(rel)) continue
+        if (found.size >= maxFiles) throw new Error(`匹配文件数超过上限 max_files=${maxFiles}，请收窄 glob 或提高上限`)
+        let st
+        try {
+          st = fs.statSync(abs)
+        } catch {
+          continue
+        }
+        found.set(rel, { size: st.size, mtimeMs: Math.floor(st.mtimeMs) })
+      }
+    }
+  }
+
+  return { entries: [...found.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1)), scanned }
+}
+
+function hashFile(abs, maxBytes) {
+  const st = fs.statSync(abs)
+  if (st.size > maxBytes) return { digest: null, size: st.size }
+  const h = crypto.createHash("sha256")
+  h.update(fs.readFileSync(abs))
+  return { digest: h.digest("hex"), size: st.size }
+}
+
+export function sha256Text(s) {
+  return crypto.createHash("sha256").update(String(s), "utf8").digest("hex")
+}
+
+/** 递归按键升序排序后序列化，用于稳定摘要（不受字段顺序影响） */
+export function canonicalize(value) {
+  if (Array.isArray(value)) return "[" + value.map((v) => canonicalize(v)).join(",") + "]"
+  if (value && typeof value === "object") {
+    return (
+      "{" +
+      Object.keys(value)
+        .sort()
+        .map((k) => JSON.stringify(k) + ":" + canonicalize(value[k]))
+        .join(",") +
+      "}"
+    )
+  }
+  return JSON.stringify(value)
+}
+
+// ---------------------------------------------------------------------------
+// 参数归一
+// ---------------------------------------------------------------------------
+
+function normalizeTasks(list) {
+  if (list === undefined || list === null) return []
+  if (!Array.isArray(list)) throw new Error("open_tasks 必须为数组")
+  return list.map((item, i) => {
+    if (typeof item === "string") {
+      const t = item.trim()
+      if (t === "") throw new Error(`open_tasks[${i}] 不能为空`)
+      return { text: t, done: false }
+    }
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error(`open_tasks[${i}] 必须为字符串或 {text, done}`)
+    }
+    const text = typeof item.text === "string" ? item.text.trim() : ""
+    if (text === "") throw new Error(`open_tasks[${i}].text 不能为空`)
+    if (item.done !== undefined && typeof item.done !== "boolean") throw new Error(`open_tasks[${i}].done 必须为布尔值`)
+    return { text, done: Boolean(item.done) }
+  })
+}
+
+function normalizeStringList(list, label) {
+  if (list === undefined || list === null) return []
+  if (!Array.isArray(list)) throw new Error(`${label} 必须为数组`)
+  return list.map((item, i) => {
+    if (typeof item !== "string" || item.trim() === "") throw new Error(`${label}[${i}] 必须为非空字符串`)
+    return item.trim()
+  })
+}
+
+function clampNumber(value, def, min, max, label) {
+  if (value === undefined || value === null || value === "") return def
+  const n = typeof value === "string" && value.trim() !== "" ? Number(value) : value
+  if (typeof n !== "number" || !Number.isInteger(n)) throw new Error(`${label} 必须为整数`)
+  if (n < min || n > max) throw new Error(`${label} 超出范围 ${min}~${max}`)
+  return n
+}
+
+/** 读 .journal 近期条目（与 dsh-workspace-journal 的 Markdown 约定兼容） */
+export function readJournal(root, limit) {
+  const dir = path.join(root, ".journal")
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return []
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => /^\d{4}-\d{2}\.md$/.test(f))
+    .sort()
+    .reverse()
+    .slice(0, 3)
+  const items = []
+  for (const f of files) {
+    const text = fs.readFileSync(path.join(dir, f), "utf8")
+    const blocks = text.split(/^###\s+/m).slice(1)
+    for (const b of blocks) {
+      const nl = b.indexOf("\n")
+      const head = (nl === -1 ? b : b.slice(0, nl)).trim()
+      const body = (nl === -1 ? "" : b.slice(nl + 1)).trim()
+      if (body === "") continue
+      const m = head.match(/^(\S+\s+\S+)(?:\s+\[([^\]]*)\])?/)
+      items.push({
+        time: m ? m[1] : head,
+        tags: m && m[2] ? m[2].split(",").map((s) => s.trim()).filter(Boolean) : [],
+        body,
+      })
+    }
+  }
+  return items.slice(0, limit)
+}
+
+// ---------------------------------------------------------------------------
+// pack_handoff
+// ---------------------------------------------------------------------------
+
+export function packHandoff(args) {
+  const root = resolveRoot(args.root ?? process.cwd())
+  const goal = typeof args.goal === "string" ? args.goal.trim() : ""
+  if (goal === "") throw new Error("缺少必填参数 goal（一句话说清接下来要干什么）")
+  if (goal.length > 500) throw new Error("goal 长度不得超过 500 字符")
+
+  const notes = args.notes === undefined || args.notes === null ? "" : String(args.notes)
+  if (notes.length > 4000) throw new Error("notes 长度不得超过 4000 字符")
+
+  const patterns = normalizeStringList(args.files, "files")
+  const maxFiles = clampNumber(args.max_files, DEFAULT_MAX_FILES, 1, HARD_MAX_FILES, "max_files")
+  const maxHash = clampNumber(args.max_hash_bytes, DEFAULT_MAX_HASH_BYTES, 0, HARD_MAX_HASH_BYTES, "max_hash_bytes")
+  const doHash = args.hash === undefined ? true : Boolean(args.hash)
+
+  let entries = []
+  let scanned = 0
+  if (patterns.length > 0) {
+    const walk = walkWorkspace(root, patterns, {
+      maxFiles,
+      prune: args.prune === undefined ? DEFAULT_PRUNE : normalizeStringList(args.prune, "prune"),
+    })
+    entries = walk.entries
+    scanned = walk.scanned
+  }
+
+  const files = []
+  let skippedLarge = 0
+  for (const [rel, meta] of entries) {
+    const abs = path.resolve(root, rel.split("/").join(path.sep))
+    const rec = { path: rel, size: meta.size, mtime: meta.mtimeMs }
+    if (doHash) {
+      const r = hashFile(abs, maxHash)
+      if (r.digest) rec.sha256 = r.digest
+      else skippedLarge++
+    }
+    files.push(rec)
+  }
+
+  const label = args.label === undefined ? path.basename(root) : String(args.label).trim()
+  const bundle = {
+    schema: SCHEMA,
+    kind: "handoff",
+    created_at: new Date().toISOString(),
+    producer: { plugin: name, version: PLUGIN_VERSION },
+    source: { root: normSlashes(root), platform: process.platform, label },
+    state: {
+      goal,
+      decisions: normalizeStringList(args.decisions, "decisions"),
+      open_tasks: normalizeTasks(args.open_tasks),
+      notes,
+    },
+    context: {
+      patterns,
+      files,
+      stats: { matched: files.length, scanned, skipped_large: skippedLarge, hashed: doHash },
+    },
+  }
+
+  if (args.include_journal) {
+    const limit = clampNumber(args.journal_limit, 10, 1, 100, "journal_limit")
+    bundle.state.journal = readJournal(root, limit)
+  }
+
+  const body = { ...bundle }
+  delete body.integrity
+  bundle.integrity = { algo: "sha256-canonical-v1", digest: sha256Text(canonicalize(body)) }
+  return bundle
+}
+
+// ---------------------------------------------------------------------------
+// bundle 解析与完整性
+// ---------------------------------------------------------------------------
+
+export function validateBundle(b) {
+  if (!b || typeof b !== "object" || Array.isArray(b)) throw new Error("bundle 必须为对象")
+  if (typeof b.schema !== "string" || !b.schema.startsWith("handoff/")) throw new Error(`bundle.schema 缺失或不是 handoff/* 版本（收到 ${b.schema}）`)
+  if (!b.source || typeof b.source.root !== "string") throw new Error("bundle.source.root 缺失，无法做路径重映射")
+  if (!b.state || typeof b.state.goal !== "string") throw new Error("bundle.state.goal 缺失")
+  if (!b.context || !Array.isArray(b.context.files)) throw new Error("bundle.context.files 缺失（应为数组，可为空）")
+  for (const f of b.context.files) {
+    if (!f || typeof f.path !== "string" || typeof f.size !== "number") throw new Error("bundle 清单项必须含 path 与 size")
+  }
+  return true
+}
+
+export function parseBundle(input, cwdRoot = process.cwd()) {
+  if (typeof input !== "string" || input.trim() === "") throw new Error("缺少必填参数 bundle（handoff 包 JSON 字符串或文件路径）")
+  const t = input.trim()
+  let obj
+  if (t.startsWith("{")) {
+    try {
+      obj = JSON.parse(t)
+    } catch (e) {
+      throw new Error(`bundle 不是合法 JSON：${e.message}`)
+    }
+  } else {
+    const abs = path.resolve(cwdRoot, t.split("/").join(path.sep))
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error(`bundle 文件不存在：${abs}（也可直接传入 JSON 字符串）`)
+    const st = fs.statSync(abs)
+    if (st.size > BUNDLE_MAX_BYTES) throw new Error(`bundle 文件过大（${st.size} 字节 > ${BUNDLE_MAX_BYTES}）`)
+    try {
+      obj = JSON.parse(fs.readFileSync(abs, "utf8"))
+    } catch (e) {
+      throw new Error(`bundle 文件不是合法 JSON：${e.message}`)
+    }
+  }
+  validateBundle(obj)
+  return obj
+}
+
+export function verifyIntegrity(bundle) {
+  if (!bundle.integrity || typeof bundle.integrity.digest !== "string") return { ok: false, reason: "缺少 integrity 字段" }
+  const body = { ...bundle }
+  delete body.integrity
+  const actual = sha256Text(canonicalize(body))
+  if (actual !== bundle.integrity.digest) {
+    return {
+      ok: false,
+      reason: "摘要不符（bundle 被手工编辑或传输损坏）",
+      expected: bundle.integrity.digest,
+      actual,
+    }
+  }
+  return { ok: true }
+}
+
+// ---------------------------------------------------------------------------
+// 漂移检测与路径重映射
+// ---------------------------------------------------------------------------
+
+function sameRoot(a, b) {
+  const x = normSlashes(a).toLowerCase()
+  const y = normSlashes(b).toLowerCase()
+  return x === y || x + "/" === y || x === y + "/"
+}
+
+function existsFile(abs) {
+  return fs.existsSync(abs) && fs.statSync(abs).isFile()
+}
+
+/**
+ * 对 bundle 清单逐项判定 unchanged / changed / moved / missing，并按原 patterns 找出目标区新增文件。
+ * 改名识别：清单里缺失的路径，其内容若能在目标区「新增文件」中找到同一份 sha256，判为 moved 而非 missing。
+ * 前提：patterns 非空（靠它枚举目标区现状）；patterns 为空时只按清单路径逐项判定，不做改名反查。
+ */
+export function detectDrift(bundle, targetRoot, top) {
+  const entries = bundle.context.files
+  const recorded = new Set(entries.map((f) => f.path))
+
+  const patterns = Array.isArray(bundle.context.patterns) ? bundle.context.patterns : []
+  const extraList = []
+  let extraTruncated = false
+  if (patterns.length > 0) {
+    try {
+      const walk = walkWorkspace(targetRoot, patterns, { maxFiles: HARD_MAX_FILES })
+      for (const [rel, meta] of walk.entries) {
+        if (!recorded.has(rel)) extraList.push({ path: rel, size: meta.size, digest: undefined })
+      }
+    } catch {
+      extraTruncated = true
+    }
+  }
+
+  /** 目标区新增文件里内容等于 digest 的路径（哈希按需计算并缓存；一份新增内容只能被认领一次） */
+  const findByDigest = (digest, self) => {
+    if (!digest) return null
+    for (const e of extraList) {
+      if (e.path === self || e.claimed) continue
+      if (e.digest === undefined) {
+        try {
+          e.digest = hashFile(path.resolve(targetRoot, e.path.split("/").join(path.sep)), HARD_MAX_HASH_BYTES).digest
+        } catch {
+          e.digest = null
+        }
+      }
+      if (e.digest && e.digest === digest) {
+        e.claimed = true
+        return e.path
+      }
+    }
+    return null
+  }
+
+  const buckets = { unchanged: [], changed: [], moved: [], missing: [], extra: [] }
+  let hashed = 0
+
+  for (const f of entries) {
+    const abs = path.resolve(targetRoot, f.path.split("/").join(path.sep))
+    if (!existsFile(abs)) {
+      const elsewhere = findByDigest(f.sha256, f.path)
+      if (elsewhere) {
+        buckets.moved.push({ from: f.path, to: elsewhere, sha256: f.sha256 })
+        continue
+      }
+      buckets.missing.push({ path: f.path, size: f.size })
+      continue
+    }
+    const st = fs.statSync(abs)
+    if (!f.sha256) {
+      if (st.size === f.size && Math.floor(st.mtimeMs) === f.mtime) buckets.unchanged.push({ path: f.path, by: "size/mtime" })
+      else buckets.changed.push({ path: f.path, reason: "size/mtime 不符（bundle 未记录哈希）", size: st.size })
+      continue
+    }
+    hashed++
+    let cur = null
+    try {
+      cur = hashFile(abs, HARD_MAX_HASH_BYTES).digest
+    } catch {
+      cur = null
+    }
+    if (cur === null) buckets.changed.push({ path: f.path, reason: `超过 ${HARD_MAX_HASH_BYTES} 字节无法校验` })
+    else if (cur === f.sha256) buckets.unchanged.push({ path: f.path })
+    else buckets.changed.push({ path: f.path, reason: "内容已变", size: st.size })
+  }
+
+  for (const e of extraList) if (!e.claimed) buckets.extra.push({ path: e.path, size: e.size })
+
+  const cap = (arr) => ({ total: arr.length, items: arr.slice(0, top) })
+  return {
+    checked_with_hash: hashed,
+    unchanged: cap(buckets.unchanged),
+    changed: cap(buckets.changed),
+    moved: cap(buckets.moved),
+    missing: cap(buckets.missing),
+    extra: cap(buckets.extra),
+    extra_truncated: extraTruncated,
+  }
+}
+
+function driftVerdict(drift) {
+  if (drift.changed.total > 0 || drift.missing.total > 0) {
+    return { verdict: "dirty", verdict_note: `缺失 ${drift.missing.total} 项、已变 ${drift.changed.total} 项，接续前先确认原因` }
+  }
+  if (drift.moved.total > 0) {
+    return { verdict: "renamed", verdict_note: `内容都在但 ${drift.moved.total} 项路径不同（改名或移动），接续时按新路径读` }
+  }
+  return { verdict: "clean", verdict_note: "清单文件全部一致，可直接接续" }
+}
+
+/** 只替换状态文本里的来源根前缀，返回新 state 与命中明细 */
+export function remapBundle(bundle, sourceRoot, targetRoot) {
+  const state = { goal: "", decisions: [], open_tasks: [], notes: "", ...(bundle.state || {}) }
+  let count = 0
+  const samples = []
+  const push = (text) => {
+    const r = remapText(text, sourceRoot, targetRoot)
+    count += r.count
+    if (r.count > 0 && samples.length < 5 && samples.indexOf(r.text) === -1) samples.push(r.text)
+    return r.text
+  }
+  const goal = push(state.goal)
+  const notes = push(state.notes)
+  const decisions = (state.decisions || []).map(push)
+  const openTasks = (state.open_tasks || []).map((t) => ({ ...t, text: push(t.text) }))
+  const hasJournal = Array.isArray(state.journal)
+  const journal = hasJournal ? state.journal.map((j) => ({ ...j, body: push(j.body) })) : []
+  const fields = {
+    goal: goal !== state.goal,
+    decisions: decisions.filter((d, i) => d !== (state.decisions || [])[i]).length,
+    open_tasks: openTasks.filter((t, i) => t.text !== (state.open_tasks || [])[i]?.text).length,
+    notes: notes !== state.notes,
+    journal: journal.filter((j, i) => j.body !== (hasJournal ? state.journal[i]?.body : undefined)).length,
+  }
+  const nextState = { ...state, goal, notes, decisions, open_tasks: openTasks }
+  if (hasJournal) nextState.journal = journal
+  else delete nextState.journal
+  return { state: nextState, count, samples, fields }
+}
+
+export function migrateHandoff(args) {
+  const bundle = parseBundle(args.bundle)
+  const targetRoot = resolveRoot(args.target_root)
+  if (!fs.existsSync(targetRoot) || !fs.statSync(targetRoot).isDirectory()) {
+    throw new Error(`目标工作区不存在或不是目录：${targetRoot}`)
+  }
+
+  const strict = args.strict === undefined ? true : Boolean(args.strict)
+  const integrity = verifyIntegrity(bundle)
+  if (strict && !integrity.ok) {
+    const hint = integrity.expected ? `（期望 ${integrity.expected.slice(0, 12)}…，实际 ${integrity.actual.slice(0, 12)}…）` : ""
+    throw new Error(`bundle 完整性校验失败：${integrity.reason}${hint}。确认是手工编辑过的包可传 strict=false 放行`)
+  }
+
+  const sourceRoot = normSlashes(bundle.source.root)
+  const target = normSlashes(targetRoot)
+  const same = sameRoot(sourceRoot, target)
+  const remapped = same
+    ? { state: { ...(bundle.state || {}) }, count: 0, samples: [], fields: {} }
+    : remapBundle(bundle, sourceRoot, target)
+
+  const doCheck = args.check === undefined ? true : Boolean(args.check)
+  const top = clampNumber(args.top, TOP_DEFAULT, 1, TOP_CAP, "top")
+
+  const result = {
+    schema: SCHEMA,
+    same_root: same,
+    source_root: sourceRoot,
+    target_root: target,
+    integrity,
+    path_rewrites: { count: remapped.count, samples: remapped.samples, fields: remapped.fields },
+    state: remapped.state,
+    summary: {
+      files_recorded: bundle.context.files.length,
+      open_tasks: (remapped.state.open_tasks || []).filter((t) => !t.done).length,
+      decisions: (remapped.state.decisions || []).length,
+    },
+  }
+
+  if (doCheck) {
+    const drift = detectDrift(bundle, targetRoot, top)
+    const v = driftVerdict(drift)
+    result.drift = drift
+    result.verdict = v.verdict
+    result.verdict_note = v.verdict_note
+  } else {
+    result.drift = null
+    result.verdict = "unchecked"
+  }
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// HANDOFF.md 渲染
+// ---------------------------------------------------------------------------
+
+const fmtSize = (n) => (n >= 1048576 ? (n / 1048576).toFixed(2) + " MB" : n >= 1024 ? (n / 1024).toFixed(1) + " KB" : n + " B")
+
+export function renderBrief(b, extra = {}) {
+  const st = b.state || {}
+  const L = []
+  L.push(`# 工作区接续包 · ${extra.title_label || b.source.label || b.source.root}`)
+  L.push("")
+  L.push(`- 来源工作区：\`${extra.show_source_root === false ? "（已迁移，见 handoff.json 的 migrated.from_root）" : b.source.root}\``)
+  L.push(`- 生成时间：${b.created_at}`)
+  L.push(`- 产出插件：${b.producer.plugin} v${b.producer.version}（${b.schema}）`)
+  if (extra.target_root) L.push(`- 目标工作区：\`${extra.target_root}\`${extra.rewrites ? `（重映射 ${extra.rewrites} 处路径）` : ""}`)
+  if (extra.verdict) L.push(`- 接续体检：${extra.verdict}${extra.verdict_note ? " — " + extra.verdict_note : ""}`)
+  L.push("")
+  L.push("## 目标")
+  L.push("")
+  L.push(st.goal || "（未填写）")
+  L.push("")
+  if ((st.decisions || []).length > 0) {
+    L.push("## 关键决策")
+    L.push("")
+    for (const d of st.decisions) L.push(`- ${d}`)
+    L.push("")
+  }
+  const tasks = st.open_tasks || []
+  if (tasks.length > 0) {
+    L.push("## 任务清单")
+    L.push("")
+    for (const t of tasks) L.push(`- [${t.done ? "x" : " "}] ${t.text}`)
+    L.push("")
+    L.push(`（未完成 ${tasks.filter((t) => !t.done).length} / 共 ${tasks.length}）`)
+    L.push("")
+  }
+  const files = b.context.files || []
+  if (files.length > 0) {
+    L.push("## 上下文文件清单")
+    L.push("")
+    L.push("| 路径 | 大小 | 指纹（前 12） |")
+    L.push("|---|---|---|")
+    for (const f of files) L.push(`| \`${f.path}\` | ${fmtSize(f.size)} | ${f.sha256 ? "`" + f.sha256.slice(0, 12) + "`" : "—"} |`)
+    L.push("")
+    const s = b.context.stats || {}
+    L.push(
+      `共 ${files.length} 项` +
+        (s.scanned ? `（本轮扫描 ${s.scanned} 个文件` : "（") +
+        (s.skipped_large ? `${s.scanned ? "，" : ""}${s.skipped_large} 项过大未取哈希` : "") +
+        "）。"
+    )
+    L.push("")
+  }
+  const d = extra.drift
+  if (d) {
+    const row = (label, arr) => {
+      if (arr.total === 0) return `| ${label} | 0 | |`
+      const shown = arr.items.map((x) => `\`${x.path || x.from || "?"}\``).join("、")
+      const more = arr.total > arr.items.length ? ` 等共 ${arr.total} 项` : ""
+      return `| ${label} | ${arr.total} | ${shown}${more} |`
+    }
+    L.push("## 目标工作区漂移")
+    L.push("")
+    L.push("| 状态 | 数量 | 示例 |")
+    L.push("|---|---|---|")
+    L.push(row("未变", d.unchanged))
+    L.push(row("已改", d.changed))
+    L.push(row("改名", d.moved))
+    L.push(row("缺失", d.missing))
+    L.push(row("新增", d.extra))
+    L.push("")
+    L.push(`其中 ${d.checked_with_hash} 项按 sha256 精确校验。`)
+    L.push("")
+  }
+  if ((st.journal || []).length > 0) {
+    L.push("## 近期日志（.journal）")
+    L.push("")
+    for (const j of st.journal) L.push(`- ${j.time}${j.tags && j.tags.length ? ` [${j.tags.join(",")}]` : ""}：${j.body.replace(/\s+/g, " ")}`)
+    L.push("")
+  }
+  if (st.notes) {
+    L.push("## 备注")
+    L.push("")
+    L.push(st.notes)
+    L.push("")
+  }
+  L.push("---")
+  L.push("")
+  L.push("本文件由 dsh-workspace-handoff 生成；在新工作区里让模型先读 HANDOFF.md 即可接续工作。")
+  return L.join("\n")
+}
+
+// ---------------------------------------------------------------------------
+// apply_handoff
+// ---------------------------------------------------------------------------
+
+export function applyHandoff(args) {
+  const bundle = parseBundle(args.bundle)
+  const targetRoot = resolveRoot(args.target_root)
+  if (!fs.existsSync(targetRoot) || !fs.statSync(targetRoot).isDirectory()) {
+    throw new Error(`目标工作区不存在或不是目录：${targetRoot}`)
+  }
+
+  const strict = args.strict === undefined ? true : Boolean(args.strict)
+  const integrity = verifyIntegrity(bundle)
+  if (!integrity.ok && strict && !args.force) {
+    throw new Error(`bundle 完整性校验失败：${integrity.reason}。确认无误可传 force=true 强制落地`)
+  }
+
+  const mode = args.mode === undefined ? "overwrite" : String(args.mode)
+  if (!["overwrite", "skip", "versioned"].includes(mode)) throw new Error(`mode 只能是 overwrite / skip / versioned（收到 ${mode}）`)
+
+  const outDirRaw = args.out_dir === undefined ? ".handoff" : String(args.out_dir)
+  if (path.isAbsolute(outDirRaw) || normSlashes(outDirRaw).split("/").includes("..")) {
+    throw new Error(`out_dir 必须为目标工作区内的相对路径（收到 ${outDirRaw}）`)
+  }
+  const outDir = path.resolve(targetRoot, outDirRaw.split("/").join(path.sep))
+  if (!isWithin(targetRoot, outDir)) throw new Error("out_dir 越出目标工作区范围")
+
+  const dryRun = args.dry_run === undefined ? false : Boolean(args.dry_run)
+  const sourceRoot = normSlashes(bundle.source.root)
+  const target = normSlashes(targetRoot)
+  const same = sameRoot(sourceRoot, target)
+  const remapped = same
+    ? { state: { ...(bundle.state || {}) }, count: 0, samples: [] }
+    : remapBundle(bundle, sourceRoot, target)
+
+  const doCheck = args.check === undefined ? true : Boolean(args.check)
+  const top = clampNumber(args.top, TOP_DEFAULT, 1, TOP_CAP, "top")
+  const drift = doCheck ? detectDrift(bundle, targetRoot, top) : null
+  const v = drift ? driftVerdict(drift) : {}
+
+  const mdText = renderBrief({ ...bundle, source: { ...bundle.source, root: target }, state: remapped.state }, {
+    title_label: path.basename(targetRoot),
+    show_source_root: same,
+    target_root: target,
+    rewrites: remapped.count,
+    verdict: drift ? v.verdict : undefined,
+    verdict_note: drift ? v.verdict_note : undefined,
+    drift,
+  })
+
+  const written = {
+    ...bundle,
+    source: { ...bundle.source, root: target, label: path.basename(targetRoot) },
+    state: remapped.state,
+    migrated: {
+      from_root: sourceRoot,
+      to_root: target,
+      at: new Date().toISOString(),
+      path_rewrites: remapped.count,
+      same_root: same,
+      integrity_ok: integrity.ok,
+    },
+  }
+  delete written.integrity
+  written.integrity = { algo: "sha256-canonical-v1", digest: sha256Text(canonicalize(written)) }
+
+  const planned = [
+    { file: "HANDOFF.md", text: mdText },
+    { file: "handoff.json", text: JSON.stringify(written, null, 2) + "\n" },
+  ]
+
+  const actions = []
+  for (const p of planned) {
+    let abs = path.join(outDir, p.file)
+    const exists = fs.existsSync(abs)
+    if (exists && mode === "skip") {
+      actions.push({ file: p.file, action: "skipped", path: abs })
+      continue
+    }
+    if (exists && mode === "versioned") {
+      const ext = path.extname(p.file)
+      const base = path.basename(p.file, ext)
+      let n = 2
+      while (fs.existsSync(path.join(outDir, `${base}-v${n}${ext}`))) n++
+      abs = path.join(outDir, `${base}-v${n}${ext}`)
+      actions.push({ file: p.file, action: dryRun ? "planned_versioned" : "written_versioned", path: abs, bytes: Buffer.byteLength(p.text, "utf8") })
+      if (!dryRun) {
+        fs.mkdirSync(outDir, { recursive: true })
+        fs.writeFileSync(abs, p.text, "utf8")
+      }
+      continue
+    }
+    actions.push({
+      file: p.file,
+      action: dryRun ? (exists ? "planned_overwrite" : "planned_create") : exists ? "overwritten" : "created",
+      path: abs,
+      bytes: Buffer.byteLength(p.text, "utf8"),
+    })
+    if (!dryRun) {
+      fs.mkdirSync(outDir, { recursive: true })
+      fs.writeFileSync(abs, p.text, "utf8")
+    }
+  }
+
+  const landed = actions.filter((a) => ["written_versioned", "created", "overwritten"].includes(a.action)).length
+  return {
+    schema: SCHEMA,
+    dry_run: dryRun,
+    out_dir: outDirRaw,
+    same_root: same,
+    integrity,
+    path_rewrites: remapped.count,
+    verdict: drift ? v.verdict : "unchecked",
+    drift,
+    actions,
+    hint: dryRun
+      ? "dry_run=true 只给出计划，未写盘；确认后去掉 dry_run 即落地"
+      : `已落地 ${landed} 个文件；读取 ${outDirRaw}/HANDOFF.md 即可接续（本插件不删除任何既有文件）`,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 工具定义
+// ---------------------------------------------------------------------------
+
+const packHandoffTool = defineTool({
+  name: "pack_handoff",
+  description:
+    "把当前工作区的一次工作状态打包成可迁移的 handoff 包（JSON）：目标、关键决策、未完成任务、备注，" +
+    "外加按 glob 展开的上下文文件清单（相对路径 + 大小 + mtime + sha256 指纹）。" +
+    "清单只记相对路径，因此换机器、换盘符、换目录名都能解；可选把 dsh-workspace-journal 的 .journal 近期条目一并带上。" +
+    "包内含对规范化 JSON 取的 sha256 完整性摘要，供迁移与落地时校验。",
+  parameters: {
+    goal: { type: "string", description: "必填，要接续的目标（一句话说清接下来干什么，≤500 字符）" },
+    decisions: { type: "array", description: "可选，已达成的关键决策字符串数组（含口径、约束等，迁移后会被读回）" },
+    open_tasks: { type: "array", description: "可选，任务数组：元素可为字符串，或 {text, done} 对象" },
+    notes: { type: "string", description: "可选，补充备注（≤4000 字符；其中的绝对路径会在迁移时自动重映射）" },
+    files: { type: "array", description: "可选，上下文文件 glob 数组，如 [\"**/*.md\",\"src/**/*.ts\"]；不含通配符的项按直接相对路径处理" },
+    root: { type: "string", description: "可选，工作区根目录（默认当前工作目录）" },
+    label: { type: "string", description: "可选，工作区名称标注（默认取根目录名）" },
+    hash: { type: "boolean", description: "可选，是否对清单文件取 sha256（默认 true）" },
+    max_files: { type: "number", description: "可选，匹配文件数上限（1~20000，默认 2000）" },
+    max_hash_bytes: { type: "number", description: "可选，单文件取哈希的字节上限（默认 4194304）" },
+    prune: { type: "array", description: "可选，遍历剪枝目录的相对路径数组（默认 .git/node_modules/.handoff/.journal/dist/build/__pycache__）" },
+    include_journal: { type: "boolean", description: "可选，是否带上 .journal 近期日志条目（默认 false）" },
+    journal_limit: { type: "number", description: "可选，日志条目上限（1~100，默认 10）" },
+  },
+  output: { schema: { type: "string" }, render: (_a, v) => [{ type: "text", text: v }] },
+  async execute(args) {
+    if (!args || args.goal === undefined) throw new Error("缺少必填参数 goal")
+    return JSON.stringify(packHandoff(args), null, 2)
+  },
+})
+
+const migrateHandoffTool = defineTool({
+  name: "migrate_handoff",
+  description:
+    "把 handoff 包迁移到另一个工作区根：状态文本里的绝对路径按「来源根 → 目标根」重映射（容忍斜杠与反斜杠混用、" +
+    "Windows 盘符大小写差异），并按目标根校验清单文件产出漂移报告（未变 / 已改 / 改名 / 缺失 / 新增）与接续结论" +
+    "（clean / renamed / dirty）。只读盘不落盘，落地请用 apply_handoff。",
+  parameters: {
+    bundle: { type: "string", description: "必填，pack_handoff 产出的 JSON 字符串，或 bundle 文件路径（如 .handoff/handoff.json）" },
+    target_root: { type: "string", description: "必填，目标工作区根目录（绝对路径或相对当前目录）" },
+    check: { type: "boolean", description: "可选，是否执行漂移检测（默认 true）" },
+    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.bundle === undefined) throw new Error("缺少必填参数 bundle")
+    if (!args || args.target_root === undefined) throw new Error("缺少必填参数 target_root")
+    return JSON.stringify(migrateHandoff(args), null, 2)
+  },
+})
+
+const applyHandoffTool = defineTool({
+  name: "apply_handoff",
+  description:
+    "在目标工作区落地接续产物：out_dir/HANDOFF.md（人类可读接续简报，含重映射后的路径、任务复选框、文件清单与漂移表）" +
+    "与 out_dir/handoff.json（迁移后重算完整性的机器包）。同名冲突策略 overwrite / skip / versioned，支持 dry_run 只看计划；" +
+    "任何情况下不删除、不改动清单之外的既有文件。",
+  parameters: {
+    bundle: { type: "string", description: "必填，handoff 包 JSON 字符串或文件路径" },
+    target_root: { type: "string", description: "必填，目标工作区根目录" },
+    mode: { type: "string", description: "可选，同名文件冲突策略：overwrite（默认）/ skip / versioned（追加 -v2、-v3）" },
+    out_dir: { type: "string", description: "可选，落地子目录（目标工作区内相对路径，默认 .handoff）" },
+    dry_run: { type: "boolean", description: "可选，只返回写入计划不落盘（默认 false）" },
+    check: { type: "boolean", description: "可选，是否执行漂移检测并写入简报（默认 true）" },
+    strict: { type: "boolean", description: "可选，完整性校验失败时拒绝写入（默认 true）" },
+    force: { type: "boolean", description: "可选，配合 strict=false：手工编辑过的包强制落地" },
+    top: { type: "number", description: "可选，漂移明细最多列出条数（默认 50）" },
+  },
+  output: { schema: { type: "string" }, render: (_a, v) => [{ type: "text", text: v }] },
+  async execute(args) {
+    if (!args || args.bundle === undefined) throw new Error("缺少必填参数 bundle")
+    if (!args || args.target_root === undefined) throw new Error("缺少必填参数 target_root")
+    return JSON.stringify(applyHandoff(args), null, 2)
+  },
+})
+
+// ---------------------------------------------------------------------------
+// 插件入口
+// ---------------------------------------------------------------------------
+
+export function apply(ctx) {
+  ctx.tools.register(packHandoffTool)
+  ctx.tools.register(migrateHandoffTool)
+  ctx.tools.register(applyHandoffTool)
+}
+
+export { packHandoffTool, migrateHandoffTool, applyHandoffTool }

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "dsh-workspace-handoff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "keywords": [
+    "dsh",
+    "plugin",
+    "workspace",
+    "handoff",
+    "session",
+    "migrate",
+    "context",
+    "manifest",
+    "sha256",
+    "drift"
+  ],
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2"
+  },
+  "scripts": {
+    "test": "node test-plugin.js",
+    "prepublishOnly": "npm test"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "latest"
+  }
+}