1014029855/dsh-context-lens

dsh-context-lens

简体中文 | English

dsh-context-lens 是 DeepSeek Harness 的上下文观测插件。它记录每次 AgentLoop 调用模型时组装出的 provider-neutral 请求，并在会话里增加一个 上下文 页签。

用它可以看清这次请求带了哪些 system prompt、messages 和 tools，各部分占了多少空间，以及它和上一次 attempt 有什么不同。

Context Lens 只读观察 Harness 的公开运行时接缝。它不会修改发给 LLM 的请求，也不会注册模型可调用工具。

能看到什么

- 每个 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 导出。

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

兼容性

| 项目 | 已验证版本 |
| --- | --- |
| Context Lens | 0.1.0 |
| DeepSeek Harness | 0.1.0-rc.5 |
| Node.js | ^22.19.0 或 >=24.0.0 |
| 界面 | web profile |

Harness 仍在 RC 阶段快速演进。本项目只对表中版本给出已验证承诺，不默认其他 RC 拥有相同的事件、client slot 和 bundle 契约。

安装

Release tarball（推荐）

从 GitHub Releases 下载 dsh-context-lens-0.1.0.tgz，然后执行：

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

如果你在 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

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

GitHub 源码

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

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

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

allowBuilds:
dsh-context-lens: true

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

使用

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

数据与隐私

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 或公网。

配置

| 字段 | 默认值 | 含义 |
| --- | ---: | --- |
| persistMetadata | true | 是否写入只含元数据的 sidecar |
| maxAttemptsPerSession | 500 | 每个 Session 最多保留的 attempt 索引 |
| charsPerEstimatedToken | 4 | 每个估算 token 对应的 UTF-16 code unit |

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

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

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

排错

看不到“上下文”页签

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 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/。

实现边界

Context Lens 在 system-prompt/assemble 前后读取命名 assembly，在 agent/pre-step 关联 step，在 llm/stream 读取最终 provider-neutral 请求。所有 waterfall listener 都会原样调用下游 next()。

真实 AgentLoop 请求优先通过 Harness 官方 isAgentLoopRequest() marker 识别。如果 Loader 模块边界拆分了这个进程内 WeakSet，结构证明只会接受同时满足以下条件的请求：

- 不带辅助调用 purpose。
- 除 AbortSignal 外的完整请求树已深冻结。
- 当前 Session 存在开放 step。
- 完整请求 envelope 与 requestHeader() 和 deriveMessages() 的结果严格相等。

标题生成、压缩和其他不匹配的 LLM stream 都会被忽略。每条 attempt 会记录它使用了 marker 还是 session-structure 证明。

插件不会向 Session 追加自定义 event。详细请求通过 Harness Session 和只含元数据的 sidecar 重建。

开发

pnpm install
pnpm run verify
pnpm pack

pnpm run verify 会运行 lint、TypeScript 检查、全部测试、Host/Client 构建、打包契约检查和发布内容检查。发布前还应将 tarball 安装到真实 Harness web profile 做一次完整验收。

DSH 规范对应

- 插件生命周期：Host 和 Client entry 导出 Cordis apply；必需 service 通过 inject 声明；注册随 Fiber 卸载。
- 插件配置：导出 Schemastery Config，非法值在加载时失败。
- Bundle 发布：package.json#dsh.bundle.patch 指向顶层 patch 数组，profile row 使用裸包名。
- Client module table：Web client 使用 lazy factory 注册，并从 Harness 模块表解析平台依赖。
- 工具开发：本插件没有模型可调用工具，因此不使用 defineTool、tool schema 或 tool output rendering。

运行时声明以 package.json#dsh.bundle、package.json#dsh.client 和 cordis.patch.yml 为准。本包不提供官方 Loader 未定义的 dsh.plugin.json。

License

MIT