snow-The/dsh-session-handoff

@snow-the/dsh-session-handoff

DeepSeek Harness 的会话交接与上下文管理——之所以构建它，是因为现有的会话管理和上下文修剪插件是在最新的 DSH 更新之前编写的，无法覆盖完整的工作流。

为什么

长会话（比如一个 17 万行的 r32 会话）会触及上下文上限，触发反复的自动压缩，然后卡住。切换到新会话又会丢失全部进度。本插件同时解决这两半——而且不止于此：

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

工具

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

| 工具 | 用途 |
|---|---|
| handoff_status | 紧凑的会话概览：轮次、消息、工具使用、检查点、上下文压力 |
| handoff_export | 将会话解析为 /.dsh-handoff/ 下的结构化 Markdown 交接文档 + 一个可直接运行的交接包（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-flash 提供服务的每一条路由：供应商、baseURL、密钥环境变量 + 家族（ark-/sk-）、默认标记（含 vision-toolkit- 变体）、vision 包装器变体 |
| model_switch | 将 agent-default-model 指向某条路由（持久化到 settings.yaml；新会话会使用它）。可选的 vision:true 会选择 vision 包装器变体；当密钥家族缺失时会发出警告 |

为在官方 DeepSeek 和火山方舟套餐之间共享同一个模型 id 的用户而构建：model_routes 显示已配置的内容，model_switch deepseek 使用方舟通道，model_switch deepseek-official --vision 使用带 vision 包装器的官方通道。

模块 E — Web 客户端（GUI）

该插件附带一个手写的客户端 bundle（client/index.js，无需构建步骤），它在 Web GUI 中注册一个 设置区段“模型路由 / Model Routes”，将宿主工具镜像为可点击的控件：

- 模型路由面板 — 实时模型目录中的每一条路由（与聊天对话框提供的列表相同，包括任何 vision-toolkit 包装器），并显示当前聊天上下文的选择（session.requestContext()）。此处不配置任何 vision 模型——聊天对话框自身的模型列表才是唯一事实来源；排序由你决定。
- 自动故障转移（优先级列表） — 拖拽重新排序路由，删除或添加条目，保存优先级。当活动模型不可达或配额耗尽（QUOTA / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT / EMPTY_RESPONSE / AUTH / 凭据 / 适配器错误）时，会自动尝试下一条路由并继续工作——用户中断永远不会触发切换。由 GET|POST /dsh-session-handoff/failover 以及 agent/request-error + agent/request 瀑布流提供支持。
- 会话交接 — 一键将当前会话导出到 /.dsh-handoff/handoff-.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 工具仍为 agent 使用提供成本模型估算）。

宿主路由与工具共享完全相同的逻辑（enumerateRoutes、switchProvider、readAcpSection/writeAcpConfig、exportHandoffForAgent），因此 GUI 和 agent 工具永远不会出现偏差。

软增强（检测到即启用，绝非必需）

- 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-.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 包装器

开发
bash
单元测试（从 profile 目录运行，以便 @deepseek-ai/ 能够解析）
node --test test/

许可证

MIT