前言¶
在 DeepSeek Harness（DSH）里跑多轮智能体时，真正送进模型的内容往往藏在链路深处：系统提示、用户输入、工具 schema、历史轮次、工具返回与压缩摘要会随每一步递增。仅靠日志或终端输出，很难对齐「这一步相对上一步多了什么、哪一段在膨胀」。下面介绍社区插件 dsh-ctx-visualizer，它在不改动 agent loop 的前提下，把每次调用的上下文以时间线与架构视图呈现出来。
这是什么¶
dsh-ctx-visualizer 是标记为 dsh-plugin 的社区插件，维护者为 cenbonew，在插件目录中归类为模型推理；当前 GitHub 星标为 1。它面向需要细读智能体循环的开发者：在一次多轮交换里（调用模型 → 解析 tool call → 执行工具 → 回传结果 → 再次调用模型），逐步展示当时发给模型的内容、相对上一步新增的部分，以及上下文增长的方向。
插件不是 DeepSeek Harness 官方包；DeepSeek Harness 仍处于 Developer Preview，所依赖的事件与接口可能不兼容变更，使用前应对照 README 中的兼容版本。
核心功能¶
安装并在对话顶部切换到 Context Lens 后，界面大致分为三块：
-
左侧 · 回合（turns）
每个回合一张卡片：用户问题、调用次数、工具运行次数、上下文 token、耗时、常用工具等。列区域为固定高度，可滚动查看更早回合。 -
顶部 · 横向时间线
展示当前选中回合内的每一步，例如Step 1 · model call → runs bash / results fed back → Step 2 …。点击节点可切换当前步骤。 -
右侧 · 步骤详情
- Architecture（默认）：根据实际内容动态生成——系统提示按自身标题分段；工具按来源分组（MCP server / built-in）；对话历史按「user → model call → tool result」链展示，本步新增消息高亮，压缩摘要单独标出；右侧为本步流程（request → model → 各 tool call 的结果/耗时/体积 → 进入下一次 request）。
- Request context：默认只显示本步新增消息；未变化的 system 与工具列表自动折叠；提供上下文组成堆叠条（system / user input / tool results / plugin injections / assistant history / tool schemas）及 input/output tokens、cache 命中率。
- Response、Tool runs、Raw JSON（完整记录及可折叠、可复制子块）。
其他已核实能力：
- 持久化：实时采集写入
~/.dsh/ctx-visualizer/captures/，插件重载或 Harness 重启后可恢复。 - Backfill：启用插件之前的步骤，通过重放 session log 的 context 变更（含 compaction）重建，并标记为 rebuilt。
- Redaction：存储前对形如
Bearer …、sk-…、tos_…、ghp_…、xoxb-…的密钥做掩码。 - 语言：跟随 Harness 区域设置（中/英），工具栏可手动切换并记住选择。
实现上为只读观测：监听 llm/stream、agent/request、tools/execute、tools/result、agent/error 等事件，以及用 sessionQuery.readSession 做 backfill；前端为 conversation.view 插槽插件。捕获失败被 try/catch 包裹，不影响 agent 本身。
安装与启用¶
插件无 npm 依赖，README 给出的获取方式为克隆仓库：
git clone https://github.com/cenbonew/dsh-ctx-visualizer.git
随后在 DeepSeek Harness 中安装该本地 bundle，任选其一：
- 对 agent 说明：用 Plugin Manager 安装本地 bundle，路径为
/absolute/path/dsh-ctx-visualizer（需替换为实际绝对路径）。 - Settings › Plugins（若当前构建支持从本地路径安装 bundle）。
package.json 中的 dsh.bundle.patch 使项目可作为 bundle 安装；dsh.client 声明前端部分，会自动接入 Web GUI。
安装后刷新页面，在任意对话顶部切换到 Context Lens。插件启用之后的模型调用会实时捕获；更早步骤会自动从 session log backfill。
更新方式：git pull，在 Plugin Manager 中关闭再打开该 bundle（或重启 Harness），并刷新页面。
开发与自测（不依赖已安装的 Harness，且不写入 ~/.dsh）：
npm test
需要 Node.js ≥ 20（见 package.json 的 engines）。
| 项目 | 版本 |
|---|---|
| 开发与验证环境 | DeepSeek Harness Desktop 0.2.0-rc.2，@deepseek-ai/dsh-* 0.2.2-rc.1（Web GUI） |
| 运行测试 | Node.js ≥ 20 |
配置¶
尚无独立设置表单。可在 profile 的 cordis.patch.yml 里为 ctx-visualizer 行传入配置，或修改 lib/index.js 顶部的 DEFAULTS：
| Key | Default | 含义 |
|---|---|---|
capture |
true |
总开关 |
persist |
true |
写入磁盘 |
persistDir |
~/.dsh/ctx-visualizer/captures |
捕获目录（目录 0700，文件 0600） |
backfill |
true |
从 session log 重建更早步骤 |
backfillIntervalMs |
30000 |
同一会话两次 backfill 的最小间隔 |
maxStepsPerSession |
80 |
每会话保留的 live 步骤数（rebuilt 不计入） |
maxSessions |
40 |
保留的会话数 |
maxCharsPerText / maxCharsPerToolResult |
400000 / 120000 |
单块文本截断上限 |
redactSecrets |
true |
存储前脱敏 |
典型用法¶
- 按上文完成 clone 与本地 bundle 安装，刷新后打开 Context Lens。
- 正常与 agent 对话；在左侧选回合，在时间线上点选某一步。
- 在 Architecture 查看系统提示分段、工具分组与本步相对历史的增量；在 Request context 看组成条与 token/cache 信息；需要原始数据时展开 Raw JSON 并复制。
- 工具栏可切换语言、清除捕获（会删除磁盘文件）；勾选 Show aux calls 可在 live 捕获时看到辅助调用（session 标题生成、context compaction 等无法 backfill 的步骤除外）。
Agent 侧还可通过注册的 Inspect Provider CtxVisualizer，用 cordis_inspect_query 查询捕获状态（见 README「How it works」）。
适用场景与注意¶
适合谁：调试 DSH 智能体上下文膨胀、对比每步新增消息、核对 tool 参数与回传、复盘多轮 tool loop 的开发者与学习场景。
权限与隐私：插件以当前 DSH 进程权限运行；捕获内容为完整模型 上下文，可能含代码、文件片段与工具返回的业务数据，默认仅存本机、不上传。默认脱敏只识别常见密钥前缀，不能覆盖全部敏感信息；模型回复与 reasoning 暂未脱敏。分享截图或复制 JSON 前请自行检查。安装前建议浏览源码与 MIT 许可证（package.json 版本 0.1.0）。
已知限制（摘自 README）：辅助调用无法 backfill；附件在请求中会被投影为文本，rebuilt 步骤可能仍显示原始 attachment 块；字符数为估计值，精确 token 以 provider 上报的 usage 为准。
DSH 生态强调「一切皆插件」；SkillHub 插件目录 为独立社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-ctx-visualizer 把「每次模型调用究竟收到什么」做成可浏览的回合时间线与动态架构图，适合在 Harness 里做上下文级调试。插件页：https://www.skillhub.cn/plugins/cenbonew/dsh-ctx-visualizer；源码与完整说明：https://github.com/cenbonew/dsh-ctx-visualizer。异常时先核对 Harness 与 @deepseek-ai/dsh-* 版本，再在仓库 Issues 反馈。
