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。
使用
- 启动
dsh web。 - 新建或打开一个会话，至少完成一次 agent turn。
- 在 Chat / Trajectory 旁边打开 上下文 / Context。
- 从 attempt 列表选择一次请求，查看体积、来源、原始值和与上一次的差异。
- 需要提交 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。
排错
看不到“上下文”页签
- 运行
dsh --profile web --dump-config，确认包含dsh-context-lens和context-lens。 - 重启
dsh web。 - 对浏览器做一次强制刷新。
没有捕获到模型请求
采集只从插件加载之后开始。重启 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。
