dsh-xray 0.3.1 → 0.4.0

package/README.md

@@ -6,6 +6,8 @@
 
 X-ray for your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — see what's actually loaded, why, and what it costs you.
 
+![dsh-xray demo](./docs/demo.svg)
+
 [中文](./README.zh.md)
 
 > **Status: 0.2.x — static + runtime imaging.** Static commands work even when dsh cannot boot; `deps`/`health` and the agent tool need the plugin mounted.
@@ -28,6 +30,63 @@ npx dsh-xray audit       # static scan of out-of-tree plugins for sensitive touc
 
 All commands take `--profile <name>` (default `web`) and `--json`. `diff` exits `1` when the trees disagree; `health` exits `1` when any plugin is unhealthy. `attribute`, `conflicts`, and `snapshot` are fully static: they work even when dsh cannot start. `deps` and `health` read the runtime snapshot the mounted plugin maintains at `$DSH_HOME/xray/runtime.json`.
 
+## What it looks like
+
+Every row of the booted tree, attributed to the layer that introduced it — and who patched it since:
+
+```console
+$ npx dsh-xray attribute
+# 130 rows in profile "web"
+
+timer                        @deepseek-ai/dsh-base
+hmr                          @deepseek-ai/dsh-base    ← patched by @deepseek-ai/dsh-web-app [disabled]
+llm                          @deepseek-ai/dsh-base
+session-query-sqlite         @deepseek-ai/dsh-base    ← patched by @deepseek-ai/dsh-web-app
+...
+```
+
+What breaks if you disable a provider — computed from the live service store, not guesses:
+
+```console
+$ npx dsh-xray deps
+# disable-cascade (transitive consumers of each provider):
+  Loader → 5 plugin(s): AgentPresets, ClientModuleRegistry, Hmr, Include, PluginInventoryGateway
+  TimerService → 1 plugin(s): Hmr
+  SessionProjectionRegistry → 1 plugin(s): SessionProjectionCache
+```
+
+Which fields have multiple writers, and who silently wins:
+
+```console
+$ npx dsh-xray conflicts
+session-query-sqlite
+  .config: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app  (winner: @deepseek-ai/dsh-web-app)
+tool-bash
+  .disabled: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app  (winner: @deepseek-ai/dsh-web-app)
+```
+
+What every request actually carries — prompt sections observed at assembly, blended with tool schemas:
+
+```console
+$ 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:
+
+```console
+$ npx dsh-xray diff
+orphan overrides (silently skipped) (1)
+  no-such-row in ~/.dsh/profiles/web/cordis.patch.yml
+```
+
 ## 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.

package/README.zh.md

@@ -6,6 +6,8 @@
 
 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 拍 X 光——看清到底加载了什么、为什么在那、以及它悄悄花掉了你什么。
 
+![dsh-xray 演示](./docs/demo.svg)
+
 [English](./README.md)
 
 > **状态:0.2.x — 静态 + 运行时成像。** 静态命令在 dsh 起不来时照样能用;`deps`/`health` 和 agent 工具需要插件已挂载。
@@ -28,6 +30,63 @@ npx dsh-xray audit       # 对 out-of-tree 插件做敏感触点静态扫描
 
 所有命令支持 `--profile <name>`(默认 `web`)和 `--json`。`diff` 在两棵树不一致时退出码 `1`;`health` 在有插件不健康时退出码 `1`。`attribute`、`conflicts`、`snapshot` 是纯静态的:dsh 起不来时照样能跑。`deps` 和 `health` 读取已挂载插件维护在 `$DSH_HOME/xray/runtime.json` 的运行时快照。
 
+## 长什么样
+
+启动树的每一行,归因到引入它的层——以及之后谁 patch 过它:
+
+```console
+$ npx dsh-xray attribute
+# 130 rows in profile "web"
+
+timer                        @deepseek-ai/dsh-base
+hmr                          @deepseek-ai/dsh-base    ← patched by @deepseek-ai/dsh-web-app [disabled]
+llm                          @deepseek-ai/dsh-base
+session-query-sqlite         @deepseek-ai/dsh-base    ← patched by @deepseek-ai/dsh-web-app
+...
+```
+
+停用一个 provider 会连带瘫掉什么——从真实服务存储算出来,不是猜的:
+
+```console
+$ npx dsh-xray deps
+# disable-cascade (transitive consumers of each provider):
+  Loader → 5 plugin(s): AgentPresets, ClientModuleRegistry, Hmr, Include, PluginInventoryGateway
+  TimerService → 1 plugin(s): Hmr
+  SessionProjectionRegistry → 1 plugin(s): SessionProjectionCache
+```
+
+哪些字段有多个写者、谁静默赢了:
+
+```console
+$ npx dsh-xray conflicts
+session-query-sqlite
+  .config: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app  (winner: @deepseek-ai/dsh-web-app)
+tool-bash
+  .disabled: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app  (winner: @deepseek-ai/dsh-web-app)
+```
+
+每次请求实际携带什么——assembly 时观测到的 prompt sections,与工具 schema 合并计价:
+
+```console
+$ 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%    ███
+...
+```
+
+patch 行指向不存在的 id 时(dsh 静默跳过),`diff` 能抓到:
+
+```console
+$ npx dsh-xray diff
+orphan overrides (silently skipped) (1)
+  no-such-row in ~/.dsh/profiles/web/cordis.patch.yml
+```
+
 ## Agent 工具
 
 挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答"我有哪些能力 / 哪个插件提供 X / 为什么 Y 不可用"。

package/bin/xray.js

@@ -183,11 +183,25 @@ function cmdCost(args) {
   const result = model.contextCost(snap);
   if (args.json) return console.log(JSON.stringify(result, null, 2));
   console.log(
-    `~${result.totalTokens} tokens across ${result.toolCount} tool schema(s) (captured ${result.capturedAt})\n`,
+    `~${result.totalTokens} tokens: ${result.toolCount} tool schema(s) ~${result.toolTokens} + ${result.sectionCount} prompt section(s) ~${result.sectionTokens} (captured ${result.capturedAt})\n`,
   );
+  const bar = (share) => '█'.repeat(Math.max(1, Math.round(share / 2)));
+  if (result.sections.length) {
+    console.log('# prompt sections (observed at last assembly):');
+    for (const s of result.sections) {
+      console.log(
+        `${pad(s.name, 32)} ${pad(`~${s.tokens}`, 8)} ${pad(`${s.share}%`, 7)} ${bar(s.share)}`,
+      );
+    }
+    console.log();
+  } else {
+    console.log('# no prompt assembly observed yet — send one agent message first\n');
+  }
+  console.log('# tool schemas:');
   for (const t of result.tools) {
-    const bar = '█'.repeat(Math.max(1, Math.round(t.share / 2)));
-    console.log(`${pad(t.name, 28)} ${pad(`~${t.tokens}`, 8)} ${pad(`${t.share}%`, 7)} ${bar}`);
+    console.log(
+      `${pad(t.name, 32)} ${pad(`~${t.tokens}`, 8)} ${pad(`${t.share}%`, 7)} ${bar(t.share)}`,
+    );
   }
 }
 

package/docs/demo.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="720" height="446" viewBox="0 0 720 446" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="12.5">
+<rect width="720" height="446" rx="8" fill="#0d1117" stroke="#30363d"/>
+<circle cx="20" cy="17" r="5.5" fill="#ff5f56"/><circle cx="40" cy="17" r="5.5" fill="#ffbd2e"/><circle cx="60" cy="17" r="5.5" fill="#27c93f"/>
+<text x="360" y="21" fill="#8b949e" text-anchor="middle" font-size="11.5">dsh-xray — composition X-ray for DeepSeek Harness</text>
+<text x="16" y="63" fill="#7ee787">$ npx dsh-xray cost</text>
+<text x="16" y="82" fill="#e6edf3">~1625 tokens: 1 tool schema(s) ~121 + 19 prompt section(s) ~1504</text>
+<text x="16" y="120" fill="#8b949e"># prompt sections (observed at last assembly):</text>
+<text x="16" y="139" fill="#e6edf3">app:web-surface                  ~248     15.3%   ████████</text>
+<text x="16" y="158" fill="#e6edf3">tool:goal                        ~184     11.3%   ██████</text>
+<text x="16" y="177" fill="#e6edf3">tool:ralph                       ~109     6.7%    ███</text>
+<text x="16" y="196" fill="#e6edf3">tool:glob                        ~98      6%      ███</text>
+<text x="16" y="215" fill="#e6edf3">harness:source                   ~94      5.8%    ███</text>
+<text x="16" y="234" fill="#8b949e">…</text>
+<text x="16" y="272" fill="#7ee787">$ npx dsh-xray attribute</text>
+<text x="16" y="291" fill="#8b949e"># 130 rows in profile "web"</text>
+<text x="16" y="310" fill="#e6edf3">hmr             @deepseek-ai/dsh-base  ← patched by dsh-web-app [disabled]</text>
+<text x="16" y="329" fill="#e6edf3">llm             @deepseek-ai/dsh-base</text>
+<text x="16" y="348" fill="#e6edf3">session-query   @deepseek-ai/dsh-base  ← patched by dsh-web-app</text>
+<text x="16" y="386" fill="#7ee787">$ npx dsh-xray deps</text>
+<text x="16" y="405" fill="#8b949e"># disable-cascade (transitive consumers of each provider):</text>
+<text x="16" y="424" fill="#e6edf3">  Loader → 5 plugin(s): AgentPresets, ClientModuleRegistry, Hmr, …</text>
+</svg>

package/lib/index.js

@@ -1,7 +1,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
-const { snapshotRegistry, stateName } = require('./collect/runtime.js');
+const { snapshotRegistry, stateName, estimateTokens } = require('./collect/runtime.js');
 const { serviceGraph, health, shadowing, contextCost } = require('./model.js');
 
 const name = 'dsh-xray';
@@ -26,6 +26,7 @@ function apply(ctx) {
   const dir = xrayDir();
   const file = path.join(dir, 'runtime.json');
   const transitions = new Map(); // plugin name -> [{state, at}] ring buffer
+  let lastAssembly = null; // latest system-prompt assembly observation
 
   let timer = null;
   const writeSnapshot = () => {
@@ -33,6 +34,7 @@ function apply(ctx) {
     try {
       const snap = snapshotRegistry(ctx);
       snap.transitions = Object.fromEntries(transitions);
+      snap.promptAssembly = lastAssembly;
       fs.mkdirSync(dir, { recursive: true });
       const tmp = `${file}.tmp`;
       fs.writeFileSync(tmp, JSON.stringify(snap, null, 2));
@@ -59,9 +61,29 @@ function apply(ctx) {
       }
       schedule();
     });
+    // system-prompt/assemble is an expert waterfall: delegate via next(),
+    // then observe the final assembly. Purely observational — the assembly
+    // is returned unmodified.
+    const disposeAssemble = ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      const result = await next();
+      try {
+        lastAssembly = {
+          at: Date.now(),
+          sections: (result?.sections ?? []).map((s) => ({
+            name: s.name,
+            tokens: estimateTokens(s.text ?? ''),
+          })),
+        };
+      } catch {
+        /* observation must never break assembly */
+      }
+      schedule();
+      return result;
+    });
     schedule(); // initial snapshot
     return [
       disposeStatus,
+      disposeAssemble,
       () => {
         clearTimeout(timer);
         writeSnapshot(); // final state on unload
@@ -111,6 +133,7 @@ function apply(ctx) {
           async execute(args) {
             const snap = snapshotRegistry(ctx);
             snap.transitions = Object.fromEntries(transitions);
+            snap.promptAssembly = lastAssembly;
             if (args.view === 'deps') return serviceGraph(snap);
             if (args.view === 'health') return health(snap);
             if (args.view === 'cost') return contextCost(snap);

package/lib/model.js

@@ -277,18 +277,25 @@ function shadowing(snap) {
   return out;
 }
 
-/** F8: estimated context cost of each model-facing tool schema. */
+/** F8: estimated context cost — tool schemas plus prompt sections. */
 function contextCost(snap) {
   const tools = (snap.tools ?? []).slice().sort((a, b) => b.tokens - a.tokens);
-  const total = tools.reduce((sum, t) => sum + t.tokens, 0);
+  const toolTokens = tools.reduce((sum, t) => sum + t.tokens, 0);
+  const sections = (snap.promptAssembly?.sections ?? [])
+    .slice()
+    .sort((a, b) => b.tokens - a.tokens);
+  const sectionTokens = sections.reduce((sum, s) => sum + s.tokens, 0);
+  const total = toolTokens + sectionTokens;
+  const share = (n) => (total ? Math.round((n / total) * 1000) / 10 : 0);
   return {
     totalTokens: total,
+    toolTokens,
+    sectionTokens,
     toolCount: tools.length,
-    tools: tools.map((t) => ({
-      name: t.name,
-      tokens: t.tokens,
-      share: total ? Math.round((t.tokens / total) * 1000) / 10 : 0,
-    })),
+    sectionCount: sections.length,
+    tools: tools.map((t) => ({ name: t.name, tokens: t.tokens, share: share(t.tokens) })),
+    sections: sections.map((s) => ({ name: s.name, tokens: s.tokens, share: share(s.tokens) })),
+    promptObservedAt: snap.promptAssembly?.at ?? null,
     capturedAt: snap.capturedAt,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "repository": {
     "type": "git",
@@ -23,7 +23,8 @@
     "bin",
     "cordis.patch.yml",
     "README.md",
-    "README.zh.md"
+    "README.zh.md",
+    "docs"
   ],
   "dependencies": {
     "yaml": "^2.6.0"
@@ -32,7 +33,8 @@
     "test": "node --test tests/*.spec.js",
     "lint": "biome check .",
     "format": "biome check --write .",
-    "check": "biome check . && node --test tests/*.spec.js"
+    "check": "biome check . && node --test tests/*.spec.js",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 tests/*.spec.js"
   },
   "keywords": [
     "dsh-plugin",
@@ -41,7 +43,14 @@
     "cordis",
     "diagnostics",
     "introspection",
-    "plugin-tree"
+    "plugin-tree",
+    "dependency-graph",
+    "observability",
+    "audit",
+    "security-scan",
+    "token-cost",
+    "lockfile",
+    "troubleshooting"
   ],
   "dsh": {
     "bundle": {