前言¶

在 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.

它提供三类使用入口：

1. 在运行中的 harness 中增加 X-Ray tab，与 Chat、Trajectory 并列。
2. 独立 /xray 页面。
3. 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 的安全姿态是读取，不运行：

1. patch 文件中的 !!js 表达式只作为 opaque marker 解析，不求值。
2. CLI 不执行插件代码；audit 是对源码文本的模式扫描。
3. mounted plugin 只写入 $DSH_HOME/xray/。
4. entry text 实时返回，不持久化。
5. 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