前言¶
在 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
