dsh-handover

DeepSeek Harness 插件，用于管理长会话的上下文水位、交接文档与压缩流程。插件按会话角色装配工具与提示段，只使用宿主公开的扩展点，不改动 DSH 本体。

为什么需要

单个会话的上下文越用越多，用到一定程度之后，出错的可能也会随之上升；可若这时压缩上下文，或者写好交接换一个会话，又会丢掉已经积累的信息。面对这样的两难，有没有更好的取舍？

本插件一定能很好地帮助你。来试试吧；不满意，随时关闭插件并删除即可。

功能

• 起始简报：水位、闸门、活跃与沉默、阶段建议，一条命令返回。
• 交接体检：检查交接文档的结构、字段与占位符，逐条列出问题。
• 压缩与续跑：由水位与剩余压缩次数共同判定时机，由用户授权，回合结束后执行；压缩后的去向由助手在登记时选择，继续工作时续跑，任务已收尾时静默等待；状态切换与失败原因写入结果。
• 在任登记与查询：每一类会话（全局、各个项目、各个杂项任务）都登记当前在任的会话与历代编号，记录保存在工作区内的 Office.json；按名字或旧编号查询现任，不启动会话也可用命令行查询。
• 换任由会话自行办理：在任会话在用户授权后自行检查交接、建立接任会话并登记在任，不再由全局会话转交。
• 会话清点与角色：查看会话水位与状态，设定角色，建立下一代会话，归档与解归档。
• 会话间通信：会话之间可直接对话，不必经全局转述；默认沉默，任务完成不向全局报告。
• 工作区迁移：预检、复制并逐文件校验、切换、改写登记、重建链接、清理旧副本。
• 快照与迁移包：库快照、打包、校验与恢复，包内绝对路径单独体检。
• 设置页：常规卡片为压缩授权、移动全局根目录、会话角色、全局前置提示词、会话水位、通用约束条闸门、交接文档体检、插件与会话间通信守卫，末尾另有默认折叠的「使用说明」；尚未接入工作区时置顶显示「首次安装」，可一键部署文件体系、工作区与会话；已接入但还没有全局会话时显示「全局会话」卡片。

安装

从 GitHub 安装

桌面版：侧栏「插件」→「添加插件」，粘贴仓库地址 https://github.com/MingMaple/dsh-handover，装完重启 DSH。

Web 或 CLI：

dsh plugin --profile web add github:MingMaple/dsh-handover

从 npm 安装

包名为 @mingmaple/dsh-handover，版本与仓库同步：

dsh plugin --profile web add @mingmaple/dsh-handover

从本地源码安装

1. 构建：node scripts/build.mjs，产物在 dist/。
2. 用 DSH 的插件管理器安装本地目录 dist/，target 传绝对路径。
3. 在插件列表里启用，重启 DSH。
4. 首次使用按下一节「首次使用」的引导部署。

首次使用

首次安装后，工作区、文件体系与会话一次部署完成：

1. 打开设置页中的 dsh-handover，在「首次安装」卡片粘贴一个长期存在目录的绝对路径。
2. 点「一键部署」。插件在该目录内建立 _Workspace 与整套文件结构，注册为「全局」工作区，并新建一个「全局」会话。
3. 在左侧「全局」工作区打开该会话即可开始。只需先铺文件时点「仅建立文件体系」，之后再点「注册为工作区」。
4. 工作区已接入但还没有全局会话时，设置页会单独出现「全局会话」卡片，可随时补建。

命令行等价操作：ho_init(parent="<已存在目录>", register=true)，再新建一个标题含「全局」的会话。

使用

安装后直接说明要做的事，不必记命令：

想做什么	可以这样说
看整体状态	先出一份起始简报
查规则	把 Charter 第 7.2.3 节取出来
交接并压缩	先把交接文档写好，再压缩并继续
换任	写好交接，请用户授权，由本会话自己换任
查在任	现在全局是谁在任
设置角色	把 Demo1 设成项目角色，并让它整理自己的文件
自检	检查插件当前状态

四类会话

角色	提示段	工具数	说明
全局	有	24	协调会话、维护规则与交接
项目	有	11	管理单个项目库，自己写骨架档案
杂项	有	11	管理单个杂项任务
普通	无	0	不注入提示、不加载工具

代理子会话不装配 ho_ 与 peer_ 工具。宿主逐步解析工具表，子会话在解析阶段即被排除，首轮即不可用。

交接与压缩

水位	动作
低于 32%	继续
32% 至 35%	可写交接；处于关键步骤时可暂缓
35% 至 85%，已压少于 3 次	写交接、原地压缩、读交接续跑
85% 及以上，已压少于 3 次	强制压缩
任意水位，已压满 3 次	写交接、建立新会话

压缩次数用尽（默认 3 次）的判定先于水位：额度用尽后，无论水位高低均建议换任；force 不能越过额度，ho_sessions 的压缩指令（action="order", order="compact"）同样会被拒绝。

压缩须由用户在设置页点「压缩授权」，单次授权 5 分钟内有效；confirm=true 只表示意图。压缩在回合结束后执行；登记时以 resume 选择去向，继续工作时续跑，任务已收尾时不唤醒。全局交接写在 _Control_Center/records/Global_Handover.md，项目与杂项交接写在各自目录，每次写入前备份。

归档文件名为 <原文件名>_<YYYYMMDD_HHMMSS>.md，同一秒重复时追加 -2。全局与项目的归档位于 _Archives/<范围>/Handover/，杂项归档位于 _Misc/tasks/<任务>/_archive/。

换任由在任会话自行办理：写完交接后，由用户在聊天框发送 /allow-succeed，或在设置页「压缩授权」卡片内的「换任授权」区域点「允许换任」。授权一次有效，5 分钟内可用，按会话生效。随后会话调用 ho_succeed，插件依次校验授权与交接结构，按记录分配下一代编号，建立接任会话并写入角色，登记在任，投递启动提示词，并在旧交接末尾追加换任登记。任何一项校验不通过时，整体不做任何改动，并逐条列出缺项。全局的建会话与换任能力保留，作为自动流程失败时的备选方案。

设置页

设置页为单页卡片式，常用区直接展开，低频与长文段折叠。未接入工作区时，首次安装卡片置顶出现。删除旧副本须先输入「删除」两字才能解锁按钮。时间显示为 YYYY-MM-DD HH:mm 加本机时区偏移。

迁移与恢复

换盘或搬动全局根目录时，按预检、复制并校验、切换、改写登记、清理旧副本五步执行，每一步均可在设置页「移动全局根目录」卡片内完成。切换须在 DSH 完全退出后由后台助手执行，原路径随后成为链接。

详见 搬迁全局根目录。

故障处理

工具数量不符、工作区未接入、设置页刷新失败、压缩未生效、换任未执行、项目名或任务名不合法、新建会话找不到工作区、设置角色后工具未更新、迁移后原路径失效，各有对应处置。

详见 常见故障处理。

上下文开销

固定开销为工具 schema 与提示段。按 0.9.13 实测，按角色载入后，全局提示段约 385 加权 token（长路径加迁移提示行约 435），项目与杂项约 370（最坏约 419），随项目名与路径长度波动；单条工具描述最宽约 56。以上为实测参考值，不设硬性上限：某条判定需要写清楚时，优先保证表达完整。

边界与限制

• 依赖 DSH 的 ctx.compaction 服务；未挂载时压缩相关工具明确报错。
• ptc 呈现模式下，插件工具只能经程序调用。
• 会话压力读取依赖宿主保存的会话状态文件布局；字段变化时用 ho_diag 排查。
• 迁移只搬文件与清单，不改写文件内容；写死的绝对路径以体检形式报出。
• 工具可见性按每一步计算：换角色在下一轮请求即生效，不必重启 DSH。插件重载后，已存在的会话沿用旧提示段文本，需要新文本时重启一次。
• 项目名与任务名按目录名校验：项目名不超过 24 字符，任务名不超过 40 字符；不含 < > : " / \ | ? * 与控制字符；不以点或空格结尾；不使用设备保留名。名字来自自由文本时同样校验，不合法则报错且不写入磁盘。
• 卸载后残留只限 ~/.dsh/storages/dsh-handover.* 与 ~/.dsh/storages/dsh-handover/logs/，删除即可清零。

开发与测试

npm test                              # 开发自测：逐个工具跑只读用例
npm run test:blank                    # 空白 DSH 验收：临时 HOME 与空目录跑 24 工具及迁移四件
npm run test:smoke                    # 空白环境冒烟：工具装配、状态路由、浏览器半渲染、语体扫描
npm run test:migrate                  # 迁移与恢复端到端
npm run test:docs                     # 文档校验：工具名、旧数、链接、版本、语体与长度上限

源码在 src/，dist/ 为构建产物，不入版本库。服务端代码替换 dist/ 后在插件列表停用再启用即生效，不必重启 DSH；已存在的会话继续使用旧的提示段文本，需要新文本时重启 DSH 或让会话重建。客户端 bundle 不热更新，改设置页必须重建并重启 DSH。

版本

当前版本 0.9.14，首次公开版本为 0.9.6。内部版本史不随仓库发布。

支持的内核为 0.2.1-rc.2 至 0.3.0（不含 0.3.0 及其候选版），见 package.json 的 engines.dsh；0.2.2-rc.1 上的工具装配、角色裁剪与压缩调度已实测通过。

许可

MIT，见 LICENSE。