zeropointnine/dsh-compact-and-branch

dsh-compact-and-branch: /compact-and-branch

一个专注的树外 DeepSeek Harness 插件，用于将规范上下文压缩视为一个干净的会话分支点。

动机

长时间运行的编码代理会话在到达自然阶段边界之前，可能会积累大量有用的工作上下文。DSH 的 /compact 命令对于缩减该历史记录，同时保留继续所需的状态非常有用，但有时更可取的做法是将该压缩作为一个干净的分支点：在全新会话中从结果状态继续，同时让被压缩的源会话保持可独立恢复。

这在上下文窗口相对有限的情况下尤其有用——这在本地 LLM 中很常见——否则较长的代理轨迹可能需要反复压缩，并使会话边界变得更加重要。

/compact-and-branch 的预期效果是：在面向模型的效果上，与运行 /compact 并在原始会话中正常继续基本相同，区别在于继续发生在一个新的根会话中。它有意复用 DSH 的规范压缩结果，而不是引入单独的交接摘要或对会话状态进行另一次有损转换。

它的作用

/compact-and-branch：

1. 预检源会话的工作区、活动预设和当前模型选择（持久的 modelSelection 投影，回退到最新请求头，然后回退到部署默认值）。
2. 调用与内置 /compact 相同的操作：
ctx.compaction.compactNow(invocation.agent, invocation.signal, invocation.commandId)。
3. 仅在该操作成功后，才对 source.session.deriveMessages() 进行快照。这是规范检查点消息加上完整保留的近期尾部；该插件从不读取或重写 CompactionResult.summary。
4. 通过 Host sessionController.create API 创建一个新的根会话，使用源工作区、活动预设，且没有 parentSession 分叉谱系，然后通过 sessionController.selectModel 继承模型路由，这会为下一个请求持久记录一个 model/selection 事件。
5. 添加一个最小前言，随后是每条规范压缩后消息的精确副本，保留消息内容、顺序、角色、身份、来源和工具配对。然后，它将新代理的空闲轮次游标推进到已导入轮次之后，以便第一个实时响应获得不同的轮次/步骤身份，并分配一个固定的交接标题。
6. 刷新目标，然后发布一个类型化会话投影。浏览器端等待目标出现在会话列表中，刷新列表以将其临时的空白会话行替换为持久化的已填充摘要，并调用受支持的 ctx.sessions.open(targetId) API。
7. 在全新会话的聊天呈现中，隐藏合成导入轮次的检查点和保留的近期尾部行，仅保留其原生的、
可选择的 DSH 通知行：“已从上一会话导入压缩后的上下文。”该通知保持项目标准的上下文排版、颜色、展开行为和可访问性；面向模型的持久消息保持不变。

内置的 /compact 未被注册、遮蔽或修改。

安装

dsh plugin 是一个轻量的 pnpm 转发器：它在你的 profile 目录中运行 pnpm，然后为你协调 profile 的 dsh.profile.bundles 栈，因此无需手动编辑任何配置文件。从 GitHub 安装该插件：

dsh plugin --profile web add git+https://github.com/zeropointnine/dsh-compact-and-branch

or pin a release tag
dsh plugin --profile web add github:zeropointnine/dsh-compact-and-branch#v0.3.0

在某个 profile 中首次运行 dsh plugin 会自动初始化它。该 profile 的 package.json 会新增该依赖，并且 DSH 会自行将 dsh-compact-and-branch 追加到 dsh.profile.bundles（它会检测该包的 dsh.bundle 声明）。此包没有构建或安装脚本，因此从 git 托管的安装无需在 profile 的 pnpm-workspace.yaml 中添加 allowBuilds 条目。

在添加、重启、更新或移除插件后，请重启 DSH。之后若要移除：dsh plugin --profile web remove dsh-compact-and-branch。

兼容性

此版本（0.3.x）面向 DSH ^0.1.5-rc.2，并且与 0.1.1 系列彻底断代。 DSH 0.1.5 移除了此插件宿主部分所构建于其上的整个 Host API-Proxy 接口（ctx.apiProxy. 已移至拥有它的业务服务上，尤其是 ctx.sessionController），并弃用了浏览器部分所注入的 @deepseek-ai/dsh-client-runtime 包，因此单个包无法同时服务两条产品线：它们的 peer 集合互不相交。使用 DSH 0.1.1-rc.x 的用户应固定到 #v0.2.0。

在同一产品线内，该插件在可能的情况下刻意保持韧性：未知的 ManualCompactionError 代码会以原始错误失败开放，而不是给出误导性消息；而它所依赖的 DSH 接口（压缩接缝、会话事件词汇表、投影注册表）在各版本间一直保持稳定。仍有三处已记录的内部依赖，并在运行时以醒目的方式加以防护：所创建 Agent 上的空闲回合游标推进（在 setPhase 变为私有后，agent.phase 成为公共字段）、maxTokens 向目标 AgentOptions 的延续，以及从导入的延续中过滤掉 system 角色消息（DSH 0.1.5 将系统提示投影添加到了 deriveMessages()；新会话会重建自己的系统上下文，因此源的系统上下文被丢弃而不是重复）。若 DSH 更新破坏了其中任何一项，会降级为可见的初始化错误，而绝不会造成静默的历史损坏。

在展示层，客户端部分依赖三种 0.1.5 的线上格式，它们是 DSH 客户端包的契约，而非此插件的契约：会话列表行的 projectionValues 字段（导航投影的视图值所在之处）
到达——此处命名错误的读取会失败并显示“no navigation”，且是静默失败），宿主列表摘要上的
agentPreset 会话投影值（0.1.5 将其从摘要字段移走；交接通过投影读取它，因此预设继承得以保留），以及命令卡片的折叠摘要渲染规则
（单行会被截断；多行文本会变成可展开的主体，这就是为什么此插件发出的每个结果文本都刻意写成两行）。

用法

在任何会话中，输入：

/compact-and-branch

无参数。当前会话通过 DSH 的规范
/compact 机制进行压缩，然后在同一工作区中创建一个新的根会话，并使用相同的模型选择作为预设，携带压缩后的
上下文；DSH 会在浏览器中打开它。压缩后的源会话仍可独立恢复。命令卡片和新会话都通过 DSH 自带的 MarkdownText 渲染器渲染
压缩摘要——与 /compact 使用的相同、完全格式化、文档内流式呈现——通过
conversation.chat.commandview 和 conversation.chat.turnTail UI 插槽。在
新会话中，导入的历史记录会折叠在一个原生 DSH
通知行后面，只留下可见的实时对话，以及导入轮次末尾的格式化
摘要卡片。在没有
react/@deepseek-ai/dsh-client-ui-primitives 模块种子词或
slots 服务的 shell 上，该插件会回退到用于
导入检查点的原生有界上下文行。

开发

pnpm install   # 安装 @deepseek-ai/ 对等副本和 zod
pnpm test      # node --test

这些测试从与插件自身导入不同的模块实例加载宿主侧类（Session、ManualCompactionError、消息
创建器），以
检验跨包错误分类边界。它们从 DSH_HOME 环境变量解析该
实例（将其指向 DSH
检出目录的 node_modules/@deepseek-ai 目录，或检出根目录），并
回退到该包自身通过 pnpm 安装的对等副本；如果两者都
不可用，这些测试会跳过并给出提示，而不是失败。

[](https://github.com/deepseek-ai/deepseek-harness)