alloevil/dsh-xray

Name: alloevil/dsh-xray
Author: alloevil

插件Plugin 原生Native ⭐ 3 MIT 其他Other

X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.

项目介绍Project Overview

由知微Agent(zhiwei)编辑Edited by Zhiwei Agent (zhiwei)

dsh-xray 是 DeepSeek Harness 的诊断插件，聚焦组合树的可解释性。核心能力：层级归因、补丁冲突检测、声明与实际配置对比、组合快照、运行时依赖图、健康状态、上下文 token 成本估算及对插件的静态安全审计。挂载后可在 /xray 面板查看，并通过 xray_composition 工具让 Agent 自检能力。适用于排查插件归属、版本漂移和服务级联影响。提示：deps/health/cost/shadow 命令及 Agent 工具需先挂载插件；其余静态命令在 dsh 无法启动时也可运行。

dsh-xray is a diagnostic plugin for the DeepSeek Harness that explains the composition tree. Core capability: layer attribution, patch conflict detection, declared-vs-actual diff, composition snapshots, runtime service dependency graphs, plugin health, context token cost, and a static capability audit. When mounted, it serves a /xray panel and registers an xray_composition tool so agents can introspect their own capabilities. Use it to trace plugin origins, version drift, and service cascades. Caveat: deps, health, cost, shadow, and the agent tool require mounting; the remaining commands are static and run even when dsh fails to boot.

在 GitHub 查看View on GitHub

发给你的 DSH 安装Send to your DSH

请帮我了解并安装插件：【dsh-xray】【https://github.com/alloevil/dsh-xray】

把上面这条消息直接发给当前会话里的 DSH，让它帮你了解并安装。安装命令不一定准确，发给 DSH 更稳。Send this message to DSH in your current session. CLI install commands may not be accurate across systems — DSH will figure it out for you.

或使用命令行安装（适合开发者）Or use CLI install (for developers)

命令行安装CLI Install

dsh plugin --profile web add dsh-xray

把 alloevil/dsh-xray 加入你的 DSH 配置（web profile）即可启用。

READMEREADME

7.2 KB · 缓存于 2026-08-25 04:53:55 · 7.2 KB

dsh-xray — X-ray for your DeepSeek Harness

X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.

🇨🇳 中文文档

dsh-xray demo

The Problem

dsh --dump-config shows you the composed tree. The plugin panel shows you a flat list. Neither tells you why a plugin is there, what breaks if you disable it, or what it silently costs you.

dsh-xray does.

Static commands work even when dsh cannot boot; deps/health/cost/shadow and the agent tool need the plugin mounted.

CLI Commands

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

Features

🔍 Layer Attribution

Which layer introduced each active plugin: kernel bundle, profile dependency, cordis.patch.yml insert, or repository source.

📊 Declared vs. Actual Diff

Installed-but-inactive, uninstalled-but-lingering patch rows — all surfaced.

⚡ Conflict Detection

Plugins patching the same config row, and which one silently wins.

📸 Composition Snapshot

Export the effective composition as a lockfile; reproduce it elsewhere.

🌐 Service Dependency Graph

Who provides and consumes each service; what cascades if you disable X.

💊 Runtime Health

Per-plugin fiber lifecycle state, startup failures, transition history.

🤖 Agent Self-Introspection

The xray_composition tool lets agents inspect their own capability set.

🖥️ Web Panel

Mounted in dsh web, the plugin serves a zero-dependency panel at /xray — summary, health, deps (with the disable-cascade table), cost, and shadow views, live from the running composition. JSON endpoints under /xray/api/* serve the same data.

The /xray panel: deps view with the disable-cascade table

What every request actually carries — prompt sections observed at assembly, blended with tool schemas:

$ npx dsh-xray cost
~1625 tokens: 1 tool schema(s) ~121 + 19 prompt section(s) ~1504

# prompt sections (observed at last assembly):
app:web-surface                  ~248     15.3%   ████████
tool:goal                        ~184     11.3%   ██████
tool:ralph                       ~109     6.7%    ███
harness:source                   ~94      5.8%    ███
...

And when a patch row targets an id that doesn't exist (dsh skips it silently), diff catches it:

🛡️ Capability Audit

Heuristic static scan: network egress, shell, filesystem, env, eval.

Agent Tool

Mounted in the tree, dsh-xray registers an xray_composition tool (view: summary | deps | health | cost | shadow), so an agent can answer:

"What capabilities do I have?" / "What plugin provides X?" / "Why is Y unavailable?"

— about itself.

Safety Stance

dsh-xray reads; it never runs.

Loader !!js expressions in patch files are parsed as opaque markers and never evaluated
The CLI never executes plugin code (audit is a pattern scan over source text)
The mounted plugin writes only under $DSH_HOME/xray/
See SECURITY.md

Install

Two ways to use it — they're independent:

1. Static CLI only (no install into dsh; works even when dsh cannot boot):

npx dsh-xray attribute        # requires Node >= 22

2. Mount the plugin (adds the runtime commands, the /xray panel, and the agent tool):

dsh plugin --profile web add dsh-xray
# bundle plugins take effect on the next start — restart dsh web

Verify it took:

dsh --profile web --dump-config | grep dsh-xray   # row present in the composed tree
npx dsh-xray health                               # reads the runtime snapshot
# then open http://localhost:3080/xray for the live panel

Uninstall: dsh plugin --profile web remove dsh-xray.

All commands take --profile <name> (default web) and --json.

Command	Behavior
`diff`	Exits `1` when the trees disagree
`health`	Exits `1` when any plugin is unhealthy
`attribute`, `conflicts`, `snapshot`	Fully static — work even when dsh cannot start
`deps`, `health`	Read runtime snapshot at `$DSH_HOME/xray/runtime.json`

Capabilities

Diagnostic imaging for a running composition — complementary to dsh-doctor (rescue & recovery).

Feature	Category
Layer attribution	🔍 Inspection
Declared vs. actual diff	🔍 Inspection
Conflict detection	🔍 Inspection
Composition snapshot	📦 Export
Service dependency graph	🌐 Runtime
Runtime health	🌐 Runtime
Agent self-introspection	🤖 AI
Capability audit	🛡️ Security
Service shadowing	🌐 Runtime
Context cost	💰 Optimization

License

MIT

渲染基于仓库 alloevil/dsh-xray 的 README.md。在 GitHub 查看原文 →

命令行安装CLI Install 复制安装命令Copy Install