前言¶
在 DSH 的「一切皆插件」模式下，插件會向每次請求寫入 prompt sections、tool schemas 等上下文。對智能體開發者和插件維護者來說，問題不只是“裝了什麼”，還包括：這些內容來自哪一層、爲什麼存在、禁用它會牽動誰、每次請求會消耗多少 token。
dsh-xray 是面向 DeepSeek Harness 的上下文透視工具。它把實際加載內容、組合關係和上下文成本拆開，給出可檢查的數據。
這是什麼¶
dsh-xray 是 alloevil/dsh-xray 項目，license 爲 MIT，package.json 版本爲 0.10.2。
它的一句話定位是：X-ray for your DeepSeek Harness — see what’s actually loaded, why, and what it costs you.
它提供三類使用入口：
- 在運行中的 harness 中增加 X-Ray tab，與 Chat、Trajectory 並列。
- 獨立
/xray頁面。 - CLI 命令。
它關注的主要問題是 LLM context-cost observability：per-plugin token attribution、prompt-section 和 tool-schema pricing、skill catalog tax、dependency cascades。
核心功能¶
上下文成本歸因¶
dsh-xray 會把每次請求中的上下文開銷按插件拆開：
- Per-plugin rollup：prompt sections、tool schemas、tokens、share，並按成本排序。
- Entry inspection：通過
/xray/api/entry返回某條 entry 的 live text，並帶 chars/tokens ruler；該文本按請求計算，不落盤。 - Skill cost view：對每條 skill catalog line 和 skill body 做成本計價；它只負責計價，開關管理仍屬於生態中的 skill managers。
- Per-request ledger：按一次 LLM 請求拆分 system、tool schemas、history、tool results；tool results 按 tool 聚合，並展示 Δprev 增長和 prefix-stability markers。
插件組合診斷¶
dsh-xray 的 CLI 提供以下命令：
attribute：查看哪些 layer 引入了每個 row，以及之後由誰 patch。conflicts：查看哪些字段有多個 writer，以及誰最終生效。diff：對比 declared 靜態 layers 和 actual dump-config 樹。snapshot：導出當前 effective composition 的 content-addressed lockfile。deps [svc]：查看服務依賴圖，包括 providers、consumers 和 disable-cascade。health：查看 plugin lifecycle health，包括 failed fibers、pending injects、transitions。cost：查看上下文成本，包括 prompt sections 和 tool schemas 的估算 token。shadow：查看由多個插件提供的同名服務。audit：對 out-of-tree plugins 做靜態掃描，檢查 sensitive touchpoints。
其中，attribute、conflicts 和 snapshot 是完全靜態的，即使 dsh 無法啓動也可以使用。
Agent 工具¶
掛載後，dsh-xray 會註冊 xray_composition agent tool，支持以下 views：
summary
deps
health
cost
shadow
安裝與啓用¶
當前已抓取資料中，README 的 Install 部分被截斷，未提供官方安裝命令；本文不拼接安裝步驟。
已覈實的包信息如下：
- 包名：
dsh-xray - 版本：
0.10.2 - License：MIT
- Main entry：
lib/index.js - Bin：
dsh-xray - 依賴：
yaml
已覈實的 DSH 啓用元數據如下：
dsh.bundle.patch：./cordis.patch.yml- Client platform：
web - Inject 模塊：
@deepseek-ai/dsh-client-runtime@deepseek-ai/dsh-client-locale@deepseek-ai/dsh-client-ui-slots@deepseek-ai/dsh-client-ui-conversation
典型用法¶
以下命令來自已覈實的 usage examples：
npx dsh-xray attribute # which layer introduced each row, and who patched it since
npx dsh-xray conflicts # rows whose fields have multiple writers, and who wins
npx dsh-xray diff # declared (static layers) vs actual (dump-config) tree
npx dsh-xray snapshot # content-addressed lockfile of the effective composition
npx dsh-xray deps [svc] # service dependency graph: providers, consumers, disable-cascade
npx dsh-xray health # plugin lifecycle health: failed fibers, pending injects, transitions
npx dsh-xray cost # context cost: prompt sections + tool schemas, estimated tokens
npx dsh-xray shadow # services provided by multiple plugins
npx dsh-xray audit # static scan of out-of-tree plugins for sensitive touchpoints
所有 CLI 命令支持：
--profile <name>
--json
其中 --profile 默認值爲 web。diff 和 health 在 drift 或 unhealth 時退出碼爲 1，可用於 CI。
在運行中的 harness 中，可以使用 X-Ray tab、獨立 /xray 頁面或 CLI。查看某條 entry 的 live text 時，可以訪問：
/xray/api/entry
該接口返回 entry 的即時文本，並附帶 chars/tokens ruler。
安全邊界¶
dsh-xray 的安全姿態是讀取，不運行：
- patch 文件中的
!!js表達式只作爲 opaque marker 解析，不求值。 - CLI 不執行插件代碼；
audit是對源碼文本的模式掃描。 - mounted plugin 只寫入
$DSH_HOME/xray/。 - entry text 即時返回，不持久化。
- entry endpoint 只返回 composition-layer text，不返回 session messages。
適用場景與注意¶
dsh-xray 適合以下場景：
- 排查 DSH 中多個插件共同寫入上下文造成的 token 開銷。
- 判斷某個插件爲什麼出現在 effective composition 中。
- 查看禁用某個插件會牽動哪些服務。
- 對比 declared 配置和 actual dump-config 結果。
- 在 CI 中檢查組合漂移或插件健康狀態。
- 讓 agent 通過
xray_composition查看自身插件組合。
需要注意：
- 插件以當前 dsh 進程權限運行，安裝前應檢查源碼和許可證。
audit是靜態掃描，不是動態執行環境驗證。- 當前資料未提供完整安裝命令，具體安裝方式應以 GitHub 倉庫說明爲準。
結尾¶
dsh-xray 的價值在於把“實際加載了什麼、爲什麼加載、每次請求花了多少”從經驗判斷變成可檢查的數據。它既可以作爲 X-Ray tab 用在運行中的 harness，也可以作爲 CLI 用於靜態診斷和 CI 檢查。
倉庫地址：https://github.com/alloevil/dsh-xray
