前言¶

在 DeepSeek Harness（DSH）里跑智能体，会话一拉长，历史会反复进上下文：Token 成本随长度涨，模型对早期内容的注意力也会变弱。常见应对是手动开新会话、自己复制粘贴进度，或依赖压缩——前者费事且容易漏关键决策，后者不一定在「当前 Step 还在跑工具或终端」时安全停下。

dsh-auto-handoff 是社区维护的工作流类 DSH 插件：在安全的 Step 边界结束当前会话，把任务与进度写成结构化交接简报，在同一工作区创建新会话并尽量继承 preset、模型、权限与 Plan 模式，由新会话接着做。触发可以是手动 /handoff，也可以按会话累计 Token 阈值自动执行。迁移不会硬中断正在执行的 Step、Tool Call、文件操作或终端命令——它只会拒绝「启动下一个 Step」。

下面介绍插件定位、能力与安装用法；事实以 GitHub 仓库 README 为准。DSH 生态是「一切皆插件」；SkillHub 目录页 为独立社区站点，与 DeepSeek / 幻方无官方从属关系。

这是什么¶

• 名称：dsh-auto-handoff（npm 包名与 Cordis 插件 name 一致）
• 维护者：qingyou002
• 分类：工作流
• 许可：MIT
• 事实基线（README 声明）：@deepseek-ai/dsh@0.1.5-rc.3

插件把长会话里的「总体目标 / 约束 / 已完成 / 当前进度 / 已改文件 / 关键决策 / 已知问题 / 未完成 / 下一步」九个小节，连同程序直接读取的原会话配置，渲染成固定结构的交接简报；简报由当前会话自己的模型生成摘要部分。旧会话标记为 retired，不再参与后续工作。

核心功能¶

Step 边界迁移，而非硬中断¶

迁移只在 Step 边界发生：不会打断正在跑的 Step、Tool Call、文件操作或终端命令。若 Token 阈值或 /handoff 已触发，插件会等待当前 Step 结束再执行后续动作；stepWaitTimeoutMs 超时只提示，不中断。

手动与自动两种触发¶

另有可选的 Token 阈值自动压缩（autoCompactEnabled / autoCompactThreshold），与自动迁移共用阈值判定与闩锁逻辑；两个开关都开启时，压缩阈值必须小于迁移阈值，否则设置无法保存。

斜杠命令¶

命令不进入模型可见历史。

空白会话（既无人类提示也无任何 turn）会被拒绝，提示「当前没有可迁移的活动会话」，不会创建无法继续的空会话。

配置继承¶

迁移时会在新会话上尽可能继承：

• 工作区 cwd 与工作区归属（按路径 attachSession）
• Agent preset、模型、权限预设（含 custom 时的审批策略）
• Plan 模式（按 agent 解析，per-agent 语义）

浏览器私有 UI 状态、未落到会话上的临时模型/权限、原会话日志与附件不继承；继承结果会逐项报告「已继承 / 回退 / 未继承（原因）」。若 sessionController 或摘要所需的 llm 不可用，迁移会失败并明确报错，不会静默吞掉。

Token 判定与自动功能¶

累计口径（会话级，compaction 不会把它归零）：

cumulative = totals.uncachedInputTokens
           + totals.outputTokens
           + totals.cacheReadTokens
           + totals.cacheWriteTokens

来源优先级：tokenUsage 投影 → tokenMeter.measure() 估算 → 不可用。标注为 unavailable 时自动迁移/压缩停用，手动 /handoff 仍可用。

安装与启用¶

安装命令来自仓库 README；装完需重启 dsh 才生效。包内带预构建 lib/，从 GitHub 直装无需在 profile 里为构建脚本加 allowBuilds 白名单。

# 从 GitHub 直装（推荐）
dsh plugin --profile <profile> add github:qingyou002/dsh-auto-handoff

# 或从本地检出的源码安装
dsh plugin --profile <profile> add "file:/path/to/dsh-auto-handoff"

package.json 声明了 dsh.bundle.patch 与 dsh.client（platform: "web"），Host 与浏览器端会自动挂载；浏览器半无需额外 profile 行。

设置命名空间为 dsh-auto-handoff；有 settings 服务时写入设置文档并重启后仍生效，没有时仅本次进程内有效。设置卡 Slot 为 settings.plugin.item，key: "dsh-auto-handoff"。

主设置默认值¶

关闭全部自动功能：将上述两个 boolean 都设为 false；手动命令仍可用。

典型用法¶

1. 安装插件并重启 dsh，在设置里按需打开 autoHandoffEnabled 并调整阈值，或保持默认、完全用手动迁移。
2. 长任务进行中，在合适时机执行 /handoff，或等待累计 Token 触达阈值；若 Agent 仍在跑 Step，等待其结束即可。
3. 用 /handoff status 查看 Token 来源（精确 / 估算 / 不可用）与动作状态；失败时用 /handoff retry，想中止排队中的动作用 /handoff cancel。
4. 迁移成功后，浏览器端默认会切到新会话（openNewSessionOnHandoff 默认为 true）；新会话首条提示为交接简报，在同一 cwd 下继续改代码、跑命令。

适用场景与注意¶

适合：单工作区内需要连续数小时以上的 Agent 任务；希望在不打断当前工具/终端的前提下换「干净上下文」；需要把 preset、模型、权限、Plan 模式一并带到新会话的开发者。

务必知晓：

• 插件以当前 dsh 进程的权限运行；安装前请阅读 源码与 LICENSE，自行评估信任边界。
• 自动功能依赖 Token 计量；适配器未上报且投影不可用时，只能用手动 /handoff。
• 两个自动开关同时开启时，须保证 autoCompactThreshold < autoHandoffThreshold；阈值过小（< 50000）会收到警告但仍可保存。
• 社区目录星标等元数据会变动；以 GitHub README 与本地 dsh 行为为准。

结尾¶

dsh-auto-handoff 解决的是长会话下的结构化交接：在 Step 边界停、写简报、同工作区开新会话并继承关键配置，而不是在工具跑到一半时强行掐断。手动 /handoff 与 Token 阈值共用同一套实现，便于在成本与注意力之间做可预期的切换。

• 目录页：https://www.skillhub.cn/plugins/qingyou002/dsh-auto-handoff
• GitHub：https://github.com/qingyou002/dsh-auto-handoff