前言¶

在 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