前言¶

在 DSH（DeepSeek Harness）里长会话跑下去，上下文窗口会逐渐被占满。常见做法是人工复制摘要、开新会话再粘贴，或者依赖外部笔记续写。dsh-auto-handoff 把「到阈值 → 拼限长交接包 → 请会话侧建新会话并送入第一条消息」做成插件化流程；2026-09-28 起还把原 dsh-session-switch 的会话切换逻辑并入本包（switch-session.js / switch-store.js）。

需要提前说明：自 2026-10-17 起，插件简介标明「换会话整条退役」——长对话续航更宜交给 DSH 官方上下文压缩，跨重启续跑交给 dsh-memory-board。下文仍按仓库 README 描述其设计与配置，便于理解历史工作流或维护已有安装。

这是什么¶

• 名称：dsh-auto-handoff（社区展示名：自动交接）
• 维护者：S3K926
• 分类：工作流
• 仓库：github.com/S3K926/dsh-auto-handoff（MIT，package 版本 1.5.0，要求 dsh >= 0.1.7-rc.2）
• 目录页：skillhub.cn 插件条目

一句话：当上下文占用达到配置比例时，生成默认上限 1200 字的交接包，并通过并入的会话切换模块开新会话、把交接包作为新会话首条消息；同时用幂等指纹避免重复交接。记忆的看/编/导入/导出不由本插件负责。

核心功能¶

阈值触发时的动作¶

占用率取值顺序（README 约定）：

1. 优先会话投影 contextPressure（与页面百分比同源）
2. 否则 ctx.tokenMeter.measure() ÷ request/context().contextWindow
3. 两者都拿不到则不动作

到阈值且满足 minTurns、冷却等条件时：

1. 拼限长交接包（默认 handoffMaxChars: 1200，只有它进入新会话）
2. 调用会话切换侧逻辑（内部 runSwitchDirect()，仍保留 /api/session/switch 等 HTTP 路由供自检与兼容）
3. 在状态目录写入幂等指纹 handoff-fingerprints.json（跨重启，最多 50 条）

本插件不自己建会话；建会话、切界面、归档原会话由并入的 switch-session.js 承担，握手失败会降级（完整待接写到约定位置，由浏览器侧自行切换）。

2026-10-16 起的默认行为变化¶

• archiveOnHandoff 默认 false：交接不写日记、状态、生长记录；指纹落在 ~/.dsh/session-switch/handoff-fingerprints.json
• autoTrigger: true 时到阈值不自动切会话，而是给 AI 塞 【自动收尾提示】；收尾完成后通过 fire-now 文件举手换会话（见下文）

职责边界¶

状态目录默认 ~/.dsh/session-switch/，可用环境变量 DSH_SESSION_SWITCH_DIR 覆盖。

Host API（前缀 /api/handoff/）¶

客户端 client.js 只负责轮询与导航/归档，不注册 slot、不写 DOM。常用路由包括：pending / take（待接）、ack、health、status、draft-report、fire、fire-ack。requestBody 须为 buffered，否则可能静默失败。

收尾后举手换会话（文件信令）¶

POST /api/handoff/fire 需宿主鉴权；AI 侧推荐写文件：

: > ~/.dsh/session-switch/fire-now

插件约每秒检测并删除该文件，客户端轮询到 fire 后替用户发送「换会话」，仍受每小时 ≤2、每天 ≤8 限制。

手动演练¶

在用户消息中整句匹配默认关键词 #交接演练：

• 只写演练副本根 sandboxRoot，不碰真档案
• 未配 sandboxRoot 则干跑并打日志
• sandboxRoot 落在真档案根内会被拒绝

安装与启用¶

安装步骤来自仓库 README（无 dsh plugin add github:... 一类单行命令）：

1. 将插件目录放入 DSH 插件源目录（示例：~/.dsh/plugin-src/dsh-auto-handoff）
2. 按本机情况修改 cordis.patch.example.yml 中的条目，写入 profile 的 cordis.patch.yml；或通过 Plugin Manager 的 install_bundle 以 bundle 安装
3. 重启宿主（改 bundle、改 config 均以重启为准，HMR 不可靠）

档案根 root 为必填逻辑：留空时依次尝试 config.root → 环境变量 DSH_MEMORY_ROOT → ~/.dsh/memory → 从当前目录向上查找。认根需同时存在 身份.md、日记.md、生长\状态.md；认不到则不动作。

配置要点¶

archiveOnHandoff: true 时写盘有四条护栏（改前备份、只改定位处、写完复核、外部改动拒写），并强制 CRLF、UTF-8 无 BOM。

典型用法与自检¶

演练交接（对话里发送，整句）：

#交接演练

模块自检（在插件目录执行）：

node index.js --selftest
node test-handoff-sandbox.mjs
node test-handoff-sandbox.mjs --verbose

会话切换自检（README 示例）：

DSH_SESSION_SWITCH_DIR=/tmp/ss node index.js --switch-selftest

适用场景与注意¶

曾经适合：本地 DSH 长会话、希望上下文到约 65% 时自动产出接手包并切会话的工作流；需要与档案目录（记忆面板体系）对齐、且接受重启宿主生效的团队。

当前生态：插件简介已标明 2026-10-17 起换会话能力退役；新部署应优先评估 DSH 官方上下文压缩与 dsh-memory-board，再决定是否保留本插件仅作交接包或档案写入逻辑。

边界（README 原文）：

• 交接包是压缩后的接手起点，不是全文复制
• 跨设备未覆盖同一 Web 客户端场景
• 插件以当前 DSH 进程权限运行，安装前请阅读源码与 MIT 许可证

结尾¶

dsh-auto-handoff 把「上下文压力 → 限长交接包 → 会话切换」串成可配置流水线，并在 2026 年多次调整默认策略（合并会话切换、默认不写档案、收尾后再举手换会话）。无论是否继续使用换会话能力，仓库 README 仍是理解阈值、冷却、指纹与 API 的权威说明。

• 社区目录：https://www.skillhub.cn/plugins/S3K926/dsh-auto-handoff
• 源码与文档：https://github.com/S3K926/dsh-auto-handoff