在 DeepSeek Harness Web UI 里实时透视上下文拼接与 Token 消耗

1. 背景与痛点

基于 DeepSeek 构建 Agent 或多轮对话应用时，上下文管理一直是“隐式”发生的：什么时候注入系统提示词、哪些历史消息被保留、哪些被裁剪或摘要、每一步真正吃掉了多少 token，通常都藏在 harness 内部，开发者只能靠日志盲猜。

尤其当上下文接近窗口上限时，harness 会自动触发 compaction（压缩/摘要历史对话），但压缩的时机、范围以及前后的 token 变化往往无法直观看到。结果就是：

• 模型突然“失忆”，不知道是哪一步被裁剪；
• token 成本上涨，找不到是哪个环节在悄悄累积；
• 调试上下文窗口疑难问题，只能反复打印日志。

bowenliang123/dsh-context 正是为了解决这个可观测性缺口而生：它把 DeepSeek Harness 内部的上下文构建过程“摊开”，在 Web UI 里实时可视化 token 历史与 compaction 事件。仓库在 7 天内收获 +578 stars，也从侧面印证了这个痛点的普遍性。

2. dsh-context 是什么

dsh-context 是一个面向 DeepSeek Harness Web UI 的上下文观测工具，核心能力可以概括为三件事：

• 实时看上下文怎么拼：每一步请求送到模型前，展示了完整消息序列是如何组装的；
• 实时看 token 怎么吃：按轮次、按消息角色统计 token 消耗与变化趋势；
• 追踪 compaction 事件：记录压缩发生的时刻、触发位置以及压缩前后的 token 数量。

它并不改变 harness 的调度逻辑，而是在旁路观测：通过劫持上下文快照，把内部状态转成结构化事件，再交给前端渲染。

3. 核心场景

3.1 上下文拼接可视化

在 Web UI 中可以看到每一次推理请求的消息列表，包括 system、user、assistant、tool 等角色，以及它们进入上下文的顺序。这样开发者能直观判断：

• 系统提示词是否被重复注入；
• 工具调用结果是否被保留或误删；
• 多轮历史是否按预期参与拼接。

3.2 Token 历史与趋势

每次请求都会记录 token 快照，形成时间序列曲线。曲线的突然上升通常意味着：

• 某条长消息被引入；
• 工具返回了超大结果；
• 历史消息未经裁剪地持续累积。

3.3 Compaction 事件回放

当触发压缩时，UI 会标记一个明确事件点，并展示：

• 触发压缩前上下文包含的消息数量和 token 数；
• 压缩后保留/摘要后的 token 数；
• 被移除或摘要化的消息范围。

这让“模型为什么忘了前文”有了直接证据，而不是事后推断。

4. 实现原理

整体思路可以概括为：劫持上下文快照 → 生成结构化事件 → 前端实时渲染。

#mermaid-svg-L0AxA5f0bRwQVYa2{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-L0AxA5f0bRwQVYa2 .error-icon{fill:#552222;}#mermaid-svg-L0AxA5f0bRwQVYa2 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-L0AxA5f0bRwQVYa2 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .marker.cross{stroke:#333333;}#mermaid-svg-L0AxA5f0bRwQVYa2 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-L0AxA5f0bRwQVYa2 p{margin:0;}#mermaid-svg-L0AxA5f0bRwQVYa2 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .cluster-label text{fill:#333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .cluster-label span{color:#333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .cluster-label span p{background-color:transparent;}#mermaid-svg-L0AxA5f0bRwQVYa2 .label text,#mermaid-svg-L0AxA5f0bRwQVYa2 span{fill:#333;color:#333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .node rect,#mermaid-svg-L0AxA5f0bRwQVYa2 .node circle,#mermaid-svg-L0AxA5f0bRwQVYa2 .node ellipse,#mermaid-svg-L0AxA5f0bRwQVYa2 .node polygon,#mermaid-svg-L0AxA5f0bRwQVYa2 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-L0AxA5f0bRwQVYa2 .rough-node .label text,#mermaid-svg-L0AxA5f0bRwQVYa2 .node .label text,#mermaid-svg-L0AxA5f0bRwQVYa2 .image-shape .label,#mermaid-svg-L0AxA5f0bRwQVYa2 .icon-shape .label{text-anchor:middle;}#mermaid-svg-L0AxA5f0bRwQVYa2 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-L0AxA5f0bRwQVYa2 .rough-node .label,#mermaid-svg-L0AxA5f0bRwQVYa2 .node .label,#mermaid-svg-L0AxA5f0bRwQVYa2 .image-shape .label,#mermaid-svg-L0AxA5f0bRwQVYa2 .icon-shape .label{text-align:center;}#mermaid-svg-L0AxA5f0bRwQVYa2 .node.clickable{cursor:pointer;}#mermaid-svg-L0AxA5f0bRwQVYa2 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .arrowheadPath{fill:#333333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-L0AxA5f0bRwQVYa2 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-L0AxA5f0bRwQVYa2 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-L0AxA5f0bRwQVYa2 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-L0AxA5f0bRwQVYa2 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-L0AxA5f0bRwQVYa2 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-L0AxA5f0bRwQVYa2 .cluster text{fill:#333;}#mermaid-svg-L0AxA5f0bRwQVYa2 .cluster span{color:#333;}#mermaid-svg-L0AxA5f0bRwQVYa2 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-L0AxA5f0bRwQVYa2 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-L0AxA5f0bRwQVYa2 rect.text{fill:none;stroke-width:0;}#mermaid-svg-L0AxA5f0bRwQVYa2 .icon-shape,#mermaid-svg-L0AxA5f0bRwQVYa2 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-L0AxA5f0bRwQVYa2 .icon-shape p,#mermaid-svg-L0AxA5f0bRwQVYa2 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-L0AxA5f0bRwQVYa2 .icon-shape .label rect,#mermaid-svg-L0AxA5f0bRwQVYa2 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-L0AxA5f0bRwQVYa2 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-L0AxA5f0bRwQVYa2 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-L0AxA5f0bRwQVYa2 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

普通请求

触发压缩

DeepSeek Harness 运行

上下文快照劫持

事件类型判断

记录消息序列与 token 数

记录 compaction 前后快照

事件总线 Event Bus

Web UI 实时推送

时间轴 / 消息列表 / Token 曲线渲染

4.1 劫持 harness 上下文快照

最核心的一步是在 harness 构建上下文、即将调用模型之前插入快照逻辑。常见的做法是在不修改上游源码的前提下，对关键方法做包装（wrap）或代理：

interface ContextSnapshot {
ts: number;
turnId: string;
messages: StoredMessage[];
tokenCount: number;
}

function snapshotContext(messages: StoredMessage[]): ContextSnapshot {
return {
ts: Date.now(),
turnId: generateTurnId(),
messages,
tokenCount: countTokens(messages),
};
}

通过包装原始的上下文构建函数，可以在模型请求发出前拿到一份“即将被模型看到”的消息序列，而不是请求完成后才拼出来的结果。

4.2 Token 历史记录

快照中的 token 数可以基于 DeepSeek 对应的分词器计算。工具会把每一次快照按时间顺序写入历史队列，并聚合出角色维度的统计：

const history: TokenPoint[] = [];

function onContextSnapshot(snapshot: ContextSnapshot) {
const byRole = groupTokensByRole(snapshot.messages);
history.push({
ts: snapshot.ts,
total: snapshot.tokenCount,
…byRole,
});
}

前端拿到 history 后，即可绘制每条消息角色各自的 token 曲线，也能看到总 token 的累积趋势。

4.3 Compaction 事件捕获

compaction 通常对应 harness 中“历史消息过于冗长时触发摘要”的路径。通过包装该路径，可以记录压缩动作的完整生命周期：

const originalCompaction = harness.compact.bind(harness);

harness.compact = async (messages, options) => {
const before = countTokens(messages);

bus.emit({
type: "compaction:start",
before,
ts: Date.now(),
});

const result = await originalCompaction(messages, options);

bus.emit({
type: "compaction:end",
before,
after: countTokens(result),
removed: messages.length – result.length,
ts: Date.now(),
});

return result;
};

这样做的好处是：事件在真正的压缩逻辑前后都被触发了，观测到的是真实行为，而不是事后推算；同时也不侵入原有实现，原始压缩逻辑仍然原样执行。

5. 前端可视化设计

Web UI 的展示重点放在“一眼看清楚”：

• 时间轴视图：每条消息按进入顺序排列，角色用不同颜色标识，token 数标注在消息块上；
• Token 曲线：总 token 与各角色 token 分开展示，compaction 点用竖线标记；
• 事件面板：列出所有 compaction 事件的摘要，点击可展开查看压缩前后对比；
• 实时推送：事件总线通过 WebSocket 或 SSE 推送最新快照，无需手动刷新。

布局上通常左侧为消息时间轴，右侧为 token 曲线与事件详情，方便在做一轮对话的同时观察系统内部的上下文变化。

6. 关键实现要点

• 快照时机：必须在上下文真正发送给模型之前完成，否则看到的是“上一轮”或“被加工后”的数据；
• 事件流设计：普通快照、token 统计、compaction 事件统一抽象为事件，便于前端复用同一条渲染链路；
• 性能控制：长对话下消息快照可能很大，可仅保留结构元信息或按需采样，避免高频推送拖垮 UI；
• 非侵入接入：优先通过包装、Hook、代理等方式接入，不硬改 harness 源码，降低升级维护成本。

7. 使用与接入

具体接入方式以仓库 README 为准，一般流程如下：

git clone https://github.com/bowenliang123/dsh-context
cd dsh-context
npm install
npm run dev

接入 harness 时，通常只需要在初始化阶段注入观测层：

import { attachContextObserver } from "dsh-context";

const harness = createDeepSeekHarness(config);

// 开启上下文观测，将事件推送到 Web UI
attachContextObserver(harness, {
endpoint: "ws://localhost:8899",
tokenizer: "deepseek",
});

示例代码为示意写法，实际接口名称与参数请以仓库最新文档为准。

随后在浏览器打开本地 Web UI，即可在实时对话过程中观察上下文拼接、token 消耗与 compaction 事件。

7.1 实战排查：工具返回超大结果触发 compaction

下面通过一次模拟故障，还原如何借助 Web UI 把“模型突然失忆”定位到某条超大工具返回结果。

1. 故障现象

某 DeepSeek Agent 负责根据用户提问查询线上日志并总结报错。一轮交互中，模型回答突然丢失了前文提到的时间范围、环境名等约束信息，同时系统记录了一次 compaction。

2. Token 曲线变化

在 dsh-context Web UI 中，token 曲线呈现三段式变化：工具调用前稳定在 45K 左右，工具返回后瞬间冲到接近窗口上限，随后触发 compaction 后回落。

#mermaid-svg-wBx6RBnrMQ39OSTF{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-wBx6RBnrMQ39OSTF .error-icon{fill:#552222;}#mermaid-svg-wBx6RBnrMQ39OSTF .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-wBx6RBnrMQ39OSTF .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-wBx6RBnrMQ39OSTF .marker{fill:#333333;stroke:#333333;}#mermaid-svg-wBx6RBnrMQ39OSTF .marker.cross{stroke:#333333;}#mermaid-svg-wBx6RBnrMQ39OSTF svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-wBx6RBnrMQ39OSTF p{margin:0;}#mermaid-svg-wBx6RBnrMQ39OSTF .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-wBx6RBnrMQ39OSTF .cluster-label text{fill:#333;}#mermaid-svg-wBx6RBnrMQ39OSTF .cluster-label span{color:#333;}#mermaid-svg-wBx6RBnrMQ39OSTF .cluster-label span p{background-color:transparent;}#mermaid-svg-wBx6RBnrMQ39OSTF .label text,#mermaid-svg-wBx6RBnrMQ39OSTF span{fill:#333;color:#333;}#mermaid-svg-wBx6RBnrMQ39OSTF .node rect,#mermaid-svg-wBx6RBnrMQ39OSTF .node circle,#mermaid-svg-wBx6RBnrMQ39OSTF .node ellipse,#mermaid-svg-wBx6RBnrMQ39OSTF .node polygon,#mermaid-svg-wBx6RBnrMQ39OSTF .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-wBx6RBnrMQ39OSTF .rough-node .label text,#mermaid-svg-wBx6RBnrMQ39OSTF .node .label text,#mermaid-svg-wBx6RBnrMQ39OSTF .image-shape .label,#mermaid-svg-wBx6RBnrMQ39OSTF .icon-shape .label{text-anchor:middle;}#mermaid-svg-wBx6RBnrMQ39OSTF .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-wBx6RBnrMQ39OSTF .rough-node .label,#mermaid-svg-wBx6RBnrMQ39OSTF .node .label,#mermaid-svg-wBx6RBnrMQ39OSTF .image-shape .label,#mermaid-svg-wBx6RBnrMQ39OSTF .icon-shape .label{text-align:center;}#mermaid-svg-wBx6RBnrMQ39OSTF .node.clickable{cursor:pointer;}#mermaid-svg-wBx6RBnrMQ39OSTF .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-wBx6RBnrMQ39OSTF .arrowheadPath{fill:#333333;}#mermaid-svg-wBx6RBnrMQ39OSTF .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-wBx6RBnrMQ39OSTF .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-wBx6RBnrMQ39OSTF .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-wBx6RBnrMQ39OSTF .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-wBx6RBnrMQ39OSTF .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-wBx6RBnrMQ39OSTF .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-wBx6RBnrMQ39OSTF .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-wBx6RBnrMQ39OSTF .cluster text{fill:#333;}#mermaid-svg-wBx6RBnrMQ39OSTF .cluster span{color:#333;}#mermaid-svg-wBx6RBnrMQ39OSTF div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-wBx6RBnrMQ39OSTF .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-wBx6RBnrMQ39OSTF rect.text{fill:none;stroke-width:0;}#mermaid-svg-wBx6RBnrMQ39OSTF .icon-shape,#mermaid-svg-wBx6RBnrMQ39OSTF .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-wBx6RBnrMQ39OSTF .icon-shape p,#mermaid-svg-wBx6RBnrMQ39OSTF .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-wBx6RBnrMQ39OSTF .icon-shape .label rect,#mermaid-svg-wBx6RBnrMQ39OSTF .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-wBx6RBnrMQ39OSTF .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-wBx6RBnrMQ39OSTF .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-wBx6RBnrMQ39OSTF :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

T1 工具调用前 45.2K token

T2 工具返回后 63.4K token

T3 触发 compaction

T4 压缩后 31.1K token

关键时间点可以整理为：

3. Compaction 事件详情

事件面板中该次 compaction:end 展示如下：

{
"type": "compaction:end",
"ts": "2026-08-28T13:41:09.214Z",
"before": { "tokens": 63402, "messages": 35 },
"after": { "tokens": 31152, "messages": 28 },
"removed": 7,
"summarizedRange": "m16..m22"
}

点击展开后可以看到，被摘要的消息范围 m16..m22 中，m16 是一条 tool 消息，token 数高达 18,432，几乎占到了压缩前总 token 的近三分之一。

4. 如何定位到工具返回的超大结果

排查路径可以简化为三步：

• 先看曲线：T2 处出现近乎垂直的上升，说明不是历史对话自然增长，而是单条消息把总 token 从 45K 拉到了 63K；
• 再看时间轴：T2 同一秒进入的是一条 tool 消息，而不是普通 user 或 assistant 消息；
• 最后查事件：compaction 摘要范围内正好包含这条 tool 消息，展开即可看到该消息的原始返回内容。

据此可以确认：问题不是历史对话自然增长，而是工具把线上查询的完整原始日志数组直接返回给了模型。

5. 修复建议

治本的方式是在工具结果进入上下文之前先做瘦身，而不是等 compaction 被动补救：

• 只返回后续推理真正需要的字段，例如 traceId、level、message、timestamp；
• 对数组结果做分页或截断，避免一次性返回全量数据；
• 对超长文本做 token 截断或摘要；
• 大结果物化到外部存储，工具只回传资源引用或查询入口。

示例：

function postProcessToolResult(result: ToolResult, maxTokens = 2000) {
const summary = {
status: result.status,
total: result.total,
traceId: result.traceId,
items: result.items.slice(0, 20),
};

const rendered = JSON.stringify(summary);
return truncateByTokens(rendered, maxTokens);
}

通过“工具层先瘦身、harness 再调度”的组合，可以从源头减少类似 compaction 的触发，让上下文窗口被真正需要的信息使用。

8. 总结

dsh-context 解决的不是“能不能聊起来”的问题，而是“聊起来之后上下文到底发生了什么”的问题。通过劫持上下文快照、记录 token 历史并捕获 compaction 事件，它把原本隐藏在 harness 内部的黑盒过程变成了可见、可追踪、可回放的可观测数据。

对于长期维护 DeepSeek Agent 应用的开发者来说，这样的工具价值在于：

• 调试上下文窗口问题时有据可查；
• 优化提示词与 token 成本时能量化对比；
• 理解 compaction 对模型记忆的影响时不再靠猜。