会话交接与上下文管理 snow-The/dsh-session-handoff

@snow-the/dsh-session-handoff

DeepSeek Harness 的会话交接与上下文管理 —— 做这个插件，是因为现有的会话管理和上下文裁剪插件都写于最新 DSH 更新之前，覆盖不了完整工作流。

为什么需要它

长会话（比如 170k 行的 r32 会话）会撞上上下文上限，反复触发自动压缩，然后卡住。换到新会话又会丢掉全部进度。这个插件把这两半都补上了 —— 还不止：

1. 交接 —— 导出结构化的可移植交接文档，让新会话能无缝接着干。
2. 主动上下文裁剪 —— 在上下文窗口填满之前压缩已用历史（走官方压缩 API，摘要由模型撰写）。
3. 会话管理 —— 回收站 / 恢复 / 彻底删除 / 列出会话。
4. 模型路由 —— 每条已注册的路由（官方 API、Ark、自定义、vision-toolkit 包装器）都能排序、能切换；每条路由可以固定自己的模型和推理强度（provider:model:effort），也可以跟随聊天当前的选择。没有任何模型 id 是写死的。
5. ACP 阈值 —— 调整压缩上限，不用碰 YAML。

工具

模块 A —— 交接（零依赖）

| 工具 | 用途 |
| handoff_status | 会话概览，紧凑呈现：轮次、消息数、工具使用情况、检查点、上下文压力 |
| handoff_export | 把会话解析成结构化 Markdown 交接文档，放在 <workspace>/.dsh-handoff/ 下，外加一个开箱即用的交接包（OpenViking 归档命令、archify 图表命令 —— 只在装了这些增强器时才有） |
| handoff_resume | 在新会话里加载最新的交接文档并继续 |

还有 /handoff 命令。

模块 B —— 主动上下文裁剪（官方压缩 API）

| 工具 | 用途 |
| acp_status | 用量、surface seq 映射、上限（软/硬压力等级） |
| acp_compress | 用你的摘要替换一段闭区间的 surface seq（ctx.compaction.compactRegion） |
| acp_decompress | 读取被检查点藏起来的原文（只读） |
| acp_search | 搜索可见的和被隐藏的已压缩历史 |
| acp_config | 显示当前生效的阈值（软/硬上限、preserveRecent、minTokens、nudge） |
| acp_set_limit | 把新阈值持久化进 settings.yaml（新会话生效） |

另外还有一个系统提示词压力横幅，超过软/硬上限（默认 60% / 70%）就提醒模型去压缩；以及一个 compaction.summarize 拦截，让摘要由模型撰写。

模块 C —— 会话管理

| 工具 | 用途 |
| session_list | 列出会话（可选包含回收站） |
| session_trash | 归档会话产物并移入插件回收站（可恢复；正在运行的会话会拒绝） |
| session_restore | 移回原位并取消归档 |
| session_purge | 永久删除产物和回收站条目 |

回收站条目以 JSON 形式保存在 $DSH_HOME/dsh-session-handoff-trash/ 下（保留最新 10 条，超出的最旧条目自动清除）。

模块 D — 模型路由（同一个模型，多个服务商）

| 工具 | 用途 |
| model_routes | 列出所有服务 deepseek-v4.1-flash 的路由：服务商、baseURL、密钥环境变量 + 密钥家族（ark-/sk-）、默认标记（含 vision-toolkit- 变体）、vision wrapper 变体 |
| model_switch | 把 agent-default-model 指向某条路由（持久化到 settings.yaml；新会话会使用它）。可选 vision:true 选中 vision wrapper 变体；密钥家族缺失时给出警告 |

专为这类用户打造：同一个模型 id 同时用在官方 DeepSeek 和火山方舟套餐上。model_routes 显示当前配置了什么，model_switch deepseek 走方舟通道，model_switch deepseek-official --vision 走官方通道并启用 vision wrapper。

模块 E — Web 客户端（GUI）

插件自带手写的客户端 bundle（client/index.js，无需构建步骤），在 Web GUI 里注册一个 设置分区「模型路由 / Model Routes」，把宿主工具映射成可点击的控件：

- 模型路由面板 — 实时模型目录里的每条路由（聊天对话框提供的同一份列表，含所有 vision-toolkit wrapper），并显示当前聊天上下文的选中项（session.requestContext()）。这里不配置 vision 模型 —— 聊天对话框自己的模型列表才是唯一来源；顺序由你决定。
- 自动故障转移（优先级列表） — 拖拽调整路由顺序，删除或新增条目，保存优先级。当前模型不可达或额度耗尽时（QUOTA / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT / EMPTY_RESPONSE / AUTH / 凭据 / 适配器错误），自动尝试下一条路由，工作继续 —— 用户主动中断永不切换。底层由 GET|POST /dsh-session-handoff/failover 以及 agent/request-error + agent/request 瀑布流支撑。
- 会话交接 — 一键把当前会话导出到 <workspace>/.dsh-handoff/handoff-<session>.md（POST /dsh-session-handoff/export）。
- 压缩阈值 — 软/硬上限滑块（17-90%），持久化到 settings.yaml 的 session-handoff: 段（GET/POST /dsh-session-handoff/acp）。「固定推荐 65/90 / Fixed 65/90」 按钮直接为 1M 窗口模型填入合理默认值（GUI 里不做逐会话计算；acp_recommend 工具仍为智能体提供成本模型估算）。

宿主路由与工具共用同一套逻辑（enumerateRoutes、switchProvider、readAcpSection/writeAcpConfig、exportHandoffForAgent），所以 GUI 和智能体工具永远不会走偏。

软增强（自动检测，绝不强制）

- OpenViking：检测到 viking_ 工具时，handoff_export 会在交接包里嵌入一条现成的 viking_remember 命令。
- archify：安装了 @tt-a1i/archify-dsh 时，交接包会附带一条 archify render 命令，用来生成进度图。

两者都不装，核心功能照常工作。

安装

dsh plugin --profile web add github:snow-The/dsh-session-handoff
重启 dsh web

用法

在旧会话里：

handoff_export → 写入 .dsh-handoff/handoff-<session>.md（+ handoff 包）

在新会话里：

handoff_resume → 加载 handoff；继续干活

长会话里干重活之前：

acp_status → 查看压力
acp_compress {start} {end} {summary} → 裁掉已用过的区间
acp_set_limit → 提前调好软/硬上限

给共享模型换服务商：

model_routes → 查看路由 model_switch deepseek → 走 Ark 通道 model_switch deepseek-official → 走官方通道 model_switch deepseek --vision → ……带上 vision 包装

开发

unit tests (run from a profile dir so @deepseek-ai/ resolves)
node --test test/

许可证

MIT