前言¶

在 DeepSeek Harness（DSH）中调试智能体时，经常需要确认每次 AgentLoop 真正组装出的 provider-neutral 请求由哪些 system、messages、tools 和调用配置组成，也要比较这次请求与上一次 attempt 的差异。dsh-context-lens 是一个只读上下文观测插件。它记录每次 AgentLoop 调用模型时组装出的 provider-neutral 请求，并在 Harness 会话中增加“上下文”/“Context”页签。

它不会修改发给 LLM 的请求，也不会注册模型可调用工具，同时不抓取网络报文。

插件定位¶

dsh-context-lens 是 DeepSeek Harness 的上下文观测插件，用于检查、测量、搜索和比较每次 AgentLoop 组装的 provider-neutral 请求。它适合排查 prompt 组装、上下文来源、请求体积和 attempt 变化等问题。

这里的请求是进入 Harness llm/stream 调度接缝的 provider-neutral GenerateOptions。Provider adapter 仍可以在后面将它转换为厂商自己的 HTTP payload；本插件不抓取网络报文。

许可证为 MIT。

核心功能¶

• 记录每次 AgentLoop 调用模型时组装出的 provider-neutral 请求。
• 在 Harness 会话中增加“上下文”/“Context”页签。
• 查看每个 turn / step / attempt 的 provider、model、system、messages、tools 和调用配置。
• 展示能对应到最终 system prompt 的命名 section；无法确定来源的内容标记为“未归因”，不做猜测。
• 展示 Harness Session 中已记录的 skill、AGENTS.md、插件 context 和 session reference 等来源信息。
• 展示 UTF-8 字节、UTF-16 code unit、Unicode code point 和逻辑 JSON 字节。
• 展示明确标为估算的 token 数；不冒充 provider tokenizer 的精确结果。
• 支持搜索、原始/结构化查看、attempt 对比和诊断 JSON 导出。
• 只读观察，不修改发给 LLM 的请求，也不注册模型可调用工具。

安装与启用¶

已验证环境¶

已验证版本如下：

该项目只对表中版本给出已验证承诺，不默认其他 RC 版本拥有相同的事件、client slot 和 bundle 契约。

Release tarball（推荐）¶

从 GitHub Releases 下载 dsh-context-lens-0.1.0.tgz 后，先安装插件，再检查配置并启动 web：

dsh plugin --profile web add ./dsh-context-lens-0.1.0.tgz
dsh --profile web --dump-config
dsh web

--dump-config 的输出中应出现 dsh-context-lens bundle layer 和 context-lens row。

如果你在 DeepSeek Harness 源码仓库中运行 CLI，在命令前加 pnpm：

pnpm dsh plugin --profile web add /path/to/dsh-context-lens-0.1.0.tgz
pnpm dsh --profile web --dump-config
pnpm dsh web

GitHub 源码¶

固定 tag 或 commit，不要跟随会移动的分支：

dsh plugin --profile web add github:1014029855/dsh-context-lens#v0.1.0

仓库会提交已构建的 lib/。pnpm 10+ 仍可能要求在 profile 的 pnpm-workspace.yaml 中允许 Git 依赖执行 prepare：

allowBuilds:
  dsh-context-lens: true

只应对已审查且已固定的源码授权。如果不想允许安装时构建，建议使用 release tarball。

典型用法¶

先启动 dsh web，新建或打开会话并完成至少一次 agent turn，然后从“上下文”页签查看某次请求。

1. 启动 web 界面：

dsh web

2. 新建或打开一个会话，至少完成一次 agent turn。
3. 在 Chat / Trajectory 旁边打开“上下文”/“Context”。
4. 从 attempt 列表选择一次请求，查看体积、来源、原始值和与上一次的差异。
5. 需要提交 bug 时，使用页面中的 JSON 导出。导出文件可能包含重建后的原始上下文，分享前请先审查。

数据与本地 API¶

dsh-context-lens 不会为原始 prompt、message 或 tool schema 再建一份持久化副本。

• 原始请求只在实时采集路径中短暂存在。
• sidecar 写入 $DSH_HOME/context-lens/v1，只保存序号引用、测量值、span、时间、健康状态和 HMAC。
• 指纹使用每个安装独立的随机密钥计算 HMAC-SHA-256，不使用裸 SHA-256。
• 本地 API 只支持 GET / HEAD，检查 loopback 对端和 Host authority，并返回 Cache-Control: no-store。不要将它直接暴露到 LAN 或公网。

配置¶

默认配置项如下：

在更后面的 profile cordis.patch.yml layer 中覆盖完整 config：

- id: context-lens
  config:
    persistMetadata: true
    maxAttemptsPerSession: 250
    charsPerEstimatedToken: 4

DSH patch 会替换这一 row 的整个 config，不会 deep merge。

更新与卸载¶

更新插件时，可以使用 release tarball：

dsh plugin --profile web add ./dsh-context-lens-0.1.0.tgz

卸载插件：

dsh plugin --profile web remove dsh-context-lens

更新或卸载后重启 dsh web。Harness 不会在卸载时自动删除插件数据。如果也要删除 capture index 和 HMAC 密钥，先停止所有 Harness 进程，再只删除 $DSH_HOME/context-lens/。

排错¶

看不到“上下文”页签¶

1. 运行 dsh --profile web --dump-config，确认输出中包含 dsh-context-lens 和 context-lens。
2. 重启 dsh web。
3. 对浏览器做一次强制刷新。

没有捕获到模型请求¶

采集只从插件加载之后开始。重启 Web profile，再新建会话并发送一条消息。不含 prompt/message 内容的健康接口是：

/context-lens/api/v1/health

recordedAttempts 应随真实 AgentLoop 请求增长。ignoredLlmStreams 计入标题生成和压缩等辅助调用，不是错误。

安装本地 tarball 失败¶

先将 tarball 放到不含空格的短路径，再将该路径传给 dsh plugin add。不要把 link: 开发 checkout 当成发布兼容证据；release 验收应使用打包后的 tarball。

适用场景与注意¶

dsh-context-lens 适合使用 DSH web profile、并且需要查看每次 AgentLoop 组装出的 provider-neutral 请求的场景。它把 attempt 变成可搜索、可比较、可导出诊断的对象，便于检查上下文组装和体积变化。

注意以下几点：

• token 数是估算值，不冒充 provider tokenizer 的精确结果。
• 它不抓取厂商 HTTP payload，也不替代 provider 侧调试。
• 它以当前 dsh 进程权限运行，安装前应检查源码、依赖和 MIT 许可证。
• 标题生成、压缩等辅助 LLM stream 会被忽略，不算错误。
• Harness 仍在 RC 阶段快速演进，升级后建议重新执行 dsh --profile web --dump-config 检查插件 row 是否正常。

参考¶

• GitHub：https://github.com/1014029855/dsh-context-lens
• 许可证：MIT