dsh-context-lens

Readme

# dsh-context-lens

简体中文 | [English](./README.en.md)

`dsh-context-lens` 是 [DeepSeek Harness](https://github.com/deepseek-ai/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`，然后执行：

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

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

```sh
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，不要跟随会移动的分支：

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

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

```yaml
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`：

```yaml
- 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 内容的健康接口是：

```text
/context-lens/api/v1/health
```

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

### 安装本地 tarball 失败

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

## 更新与卸载

```sh
# 更新
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 重建。

## 开发

```sh
pnpm install
pnpm run verify
pnpm pack
```

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

## DSH 规范对应

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

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

## License

[MIT](./LICENSE)