npm - dsh-xray - Versions diffs - 0.5.0 → 0.6.0 - Mend

dsh-xray 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -27,7 +27,7 @@
 **dsh-xray does.**
-> **Status: 0.4.x — static + runtime imaging with context-cost attribution.** Static commands work even when dsh cannot boot; `deps`/`health`/`cost`/`shadow` and the agent tool need the plugin mounted.
+> **Status: 0.6.x — static + runtime imaging, context-cost attribution, and a web panel.** Static commands work even when dsh cannot boot; `deps`/`health`/`cost`/`shadow` and the agent tool need the plugin mounted.
 ---
@@ -79,6 +79,9 @@ 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.
 What every request actually carries — prompt sections observed at assembly, blended with tool schemas:
 ```console

package/README.zh.md CHANGED Viewed

@@ -10,7 +10,7 @@
 [English](./README.md)
-> **状态:0.4.x — 静态 + 运行时成像,含上下文成本归因。** 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
+> **状态:0.6.x — 静态 + 运行时成像、上下文成本归因、Web 面板。** 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
 `dsh --dump-config` 只给你原始组合树,插件面板只给你平铺列表。它们都不回答:这个插件*为什么*在这、停用它会*连带瘫掉什么*、它在*悄悄消耗什么*。dsh-xray 回答这些。
@@ -91,6 +91,10 @@ orphan overrides (silently skipped) (1)
 挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答"我有哪些能力 / 哪个插件提供 X / 为什么 Y 不可用"。
+## Web 面板
+在 `dsh web` 中挂载后,插件在 **`/xray`** 提供零依赖面板——summary、health、deps(含停用级联表)、cost、shadow 五个视图,数据实时来自运行中的组合树;`/xray/api/*` 提供同源 JSON。
 ## 安全立场
 dsh-xray 只读不执行。patch 文件里的 loader `!!js` 表达式解析为不透明标记、绝不求值;CLI 从不执行插件代码(`audit` 是对源码文本的模式扫描);挂载的插件只写 `$DSH_HOME/xray/` 目录。详见 [SECURITY.md](./SECURITY.md)。

package/lib/index.js CHANGED Viewed

@@ -91,6 +91,43 @@ function apply(ctx) {
     ];
   }, 'xray-runtime-snapshot');
+  // Web panel: mounts when the profile composes a webServer (dsh web).
+  // Headless profiles simply never activate this subplugin.
+  ctx.plugin({
+    name: 'dsh-xray-panel',
+    inject: ['webServer'],
+    apply: (wctx) => {
+      const { mountPanel } = require('./panel.js');
+      const freshSnap = () => {
+        const snap = snapshotRegistry(ctx);
+        snap.transitions = Object.fromEntries(transitions);
+        snap.promptAssembly = lastAssembly;
+        return snap;
+      };
+      wctx.effect(
+        () =>
+          mountPanel(wctx.webServer, {
+            summary: () => {
+              const snap = freshSnap();
+              return {
+                plugins: snap.plugins.length,
+                unhealthy: health(snap).unhealthy.length,
+                services: Object.keys(serviceGraph(snap).services).length,
+                toolSchemaTokens: contextCost(snap).totalTokens,
+                capturedAt: snap.capturedAt,
+              };
+            },
+            deps: () => serviceGraph(freshSnap()),
+            health: () => health(freshSnap()),
+            cost: () => contextCost(freshSnap()),
+            shadow: () => shadowing(freshSnap()),
+          }),
+        'xray-panel-routes',
+      );
+      logger.info('xray panel mounted at /xray');
+    },
+  });
   // Agent self-introspection tool: only when a tool registry exists
   // (headless/web both have one; keep it optional so xray mounts anywhere).
   ctx.plugin({

package/lib/panel.js ADDED Viewed

@@ -0,0 +1,213 @@
+// Self-contained web panel: one HTML page + JSON endpoints, mounted on the
+// host webServer. No client-module bundle, no React, no build step — the
+// model layer already computes everything; this only renders it.
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>dsh-xray</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; margin: 0; }
+  body { font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+         background: #0d1117; color: #e6edf3; padding: 24px; }
+  h1 { font-size: 16px; margin-bottom: 4px; }
+  .sub { color: #8b949e; margin-bottom: 20px; }
+  nav { display: flex; gap: 8px; margin-bottom: 16px; flex-wrap: wrap; }
+  nav button { background: #21262d; color: #e6edf3; border: 1px solid #30363d;
+               border-radius: 6px; padding: 5px 12px; cursor: pointer; font: inherit; }
+  nav button.active { background: #1f6feb; border-color: #1f6feb; }
+  table { border-collapse: collapse; width: 100%; margin-top: 8px; }
+  th, td { text-align: left; padding: 4px 10px; border-bottom: 1px solid #21262d; }
+  th { color: #8b949e; font-weight: normal; }
+  .num { text-align: right; }
+  .bar { background: #1f6feb; height: 10px; border-radius: 2px; display: inline-block; }
+  .warn { color: #f85149; }
+  .ok { color: #7ee787; }
+  .muted { color: #8b949e; }
+  #status { margin: 12px 0; color: #8b949e; }
+  .tag { background: #21262d; border-radius: 4px; padding: 1px 6px; margin-left: 6px; font-size: 11px; }
+</style>
+</head>
+<body>
+<h1>dsh-xray</h1>
+<div class="sub">composition X-ray — live from this harness</div>
+<nav id="nav"></nav>
+<div id="status"></div>
+<div id="content"></div>
+<script>
+const views = ['summary', 'health', 'deps', 'cost', 'shadow'];
+const esc = (s) => String(s ?? '').replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
+const nav = document.getElementById('nav');
+const content = document.getElementById('content');
+const status = document.getElementById('status');
+let active = 'summary';
+for (const v of views) {
+  const b = document.createElement('button');
+  b.textContent = v;
+  b.onclick = () => { active = v; render(); };
+  b.id = 'nav-' + v;
+  nav.appendChild(b);
+}
+function table(headers, rows) {
+  return '<table><tr>' + headers.map((h) => '<th>' + esc(h) + '</th>').join('') + '</tr>'
+    + rows.join('') + '</table>';
+}
+function bar(share) {
+  return '<span class="bar" style="width:' + Math.max(2, share * 2) + 'px"></span>';
+}
+const renderers = {
+  summary(d) {
+    return table(['metric', 'value'], [
+      '<tr><td>plugins mounted</td><td class="num">' + d.plugins + '</td></tr>',
+      '<tr><td>unhealthy</td><td class="num ' + (d.unhealthy ? 'warn' : 'ok') + '">' + d.unhealthy + '</td></tr>',
+      '<tr><td>services</td><td class="num">' + d.services + '</td></tr>',
+      '<tr><td>context tokens (tools + sections)</td><td class="num">~' + d.toolSchemaTokens + '</td></tr>',
+    ]) + '<p class="muted" style="margin-top:12px">captured ' + esc(d.capturedAt) + '</p>';
+  },
+  health(d) {
+    let html = '<p><span class="ok">' + d.healthy.length + ' healthy</span>'
+      + (d.waiting.length ? ' · ' + d.waiting.length + ' waiting' : '')
+      + (d.unhealthy.length ? ' · <span class="warn">' + d.unhealthy.length + ' unhealthy</span>' : '') + '</p>';
+    if (d.unhealthy.length) {
+      html += table(['plugin', 'fiber', 'state', 'error'], d.unhealthy.flatMap((p) =>
+        p.fibers.map((f) => '<tr><td>' + esc(p.name) + '</td><td class="num">' + f.uid
+          + '</td><td class="warn">' + esc(f.state) + '</td><td>' + esc(f.error ?? '') + '</td></tr>')));
+    }
+    if (d.waiting.length) {
+      html += table(['waiting plugin', 'wants'], d.waiting.map((p) =>
+        '<tr><td>' + esc(p.name) + '</td><td>' + esc(p.inject.join(', ')) + '</td></tr>'));
+    }
+    return html;
+  },
+  deps(d) {
+    const services = Object.entries(d.services).map(([name, node]) =>
+      '<tr><td>' + esc(name) + '</td><td>' + esc(node.providers.join(', ') || '—')
+      + '</td><td>' + esc(node.consumers.join(', ') || '—') + '</td></tr>');
+    let html = table(['service', 'provided by', 'consumed by'], services);
+    const cascade = Object.entries(d.cascade);
+    if (cascade.length) {
+      html = '<h3 style="margin:8px 0">disable-cascade</h3>'
+        + table(['provider', 'affects'], cascade.map(([p, a]) =>
+          '<tr><td>' + esc(p) + '</td><td>' + esc(a.join(', ')) + '</td></tr>'))
+        + '<h3 style="margin:16px 0 8px">services</h3>' + html;
+    }
+    if (d.unsatisfied.length) {
+      html = '<p class="warn">' + d.unsatisfied.length + ' unsatisfied inject(s)</p>' + html;
+    }
+    return html;
+  },
+  cost(d) {
+    let html = '<p>~' + d.totalTokens + ' tokens: ' + d.toolCount + ' tool schema(s) ~' + d.toolTokens
+      + ' + ' + d.sectionCount + ' prompt section(s) ~' + d.sectionTokens + '</p>';
+    if (d.sections.length) {
+      html += '<h3 style="margin:12px 0 4px">prompt sections</h3>'
+        + table(['section', 'tokens', 'share', ''], d.sections.map((s) =>
+          '<tr><td>' + esc(s.name) + '</td><td class="num">~' + s.tokens + '</td><td class="num">'
+          + s.share + '%</td><td>' + bar(s.share) + '</td></tr>'));
+    } else {
+      html += '<p class="muted">no prompt assembly observed yet — send one agent message first</p>';
+    }
+    html += '<h3 style="margin:12px 0 4px">tool schemas</h3>'
+      + table(['tool', 'tokens', 'share', ''], d.tools.map((t) =>
+        '<tr><td>' + esc(t.name) + '</td><td class="num">~' + t.tokens + '</td><td class="num">'
+        + t.share + '%</td><td>' + bar(t.share) + '</td></tr>'));
+    return html;
+  },
+  shadow(d) {
+    let html = d.services.length
+      ? table(['service', 'providers'], d.services.map((s) =>
+          '<tr><td>' + esc(s.service) + '</td><td class="warn">' + esc(s.providers.join(' AND ')) + '</td></tr>'))
+      : '<p class="ok">no service is provided by more than one plugin</p>';
+    if (d.registrars.length) {
+      html += '<h3 style="margin:12px 0 4px">registrars</h3>'
+        + table(['plugin', 'registrations'], d.registrars.map((r) =>
+          '<tr><td>' + esc(r.plugin) + '</td><td class="num">' + r.registrations + '</td></tr>'));
+    }
+    return html;
+  },
+};
+async function render() {
+  for (const v of views) document.getElementById('nav-' + v).className = v === active ? 'active' : '';
+  status.textContent = 'loading ' + active + '…';
+  try {
+    const res = await fetch('/xray/api/' + active);
+    if (!res.ok) throw new Error(await res.text());
+    const data = await res.json();
+    content.innerHTML = renderers[active](data);
+    status.textContent = '';
+  } catch (err) {
+    status.innerHTML = '<span class="warn">' + esc(err.message) + '</span>';
+    content.innerHTML = '';
+  }
+}
+render();
+setInterval(() => { if (active === 'health' || active === 'summary') render(); }, 5000);
+</script>
+</body>
+</html>`;
+function sendJson(response, code, value) {
+  const body = JSON.stringify(value);
+  response.writeHead(code, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  response.end(body);
+}
+/**
+ * Mount the panel routes. `views` supplies fresh data per request:
+ * { summary, deps, health, cost, shadow } — each a () => object.
+ * Returns the disposers webServer.register produced.
+ */
+function mountPanel(webServer, views) {
+  const disposers = [];
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/xray',
+      handler: (request, response) => {
+        if (request.method !== 'GET') {
+          response.writeHead(405, { allow: 'GET' });
+          response.end();
+          return;
+        }
+        response.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'cache-control': 'no-store',
+        });
+        response.end(PAGE);
+      },
+    }),
+  );
+  for (const [name, compute] of Object.entries(views)) {
+    disposers.push(
+      webServer.register({
+        kind: 'exact',
+        path: `/xray/api/${name}`,
+        handler: (request, response) => {
+          if (request.method !== 'GET') {
+            response.writeHead(405, { allow: 'GET' });
+            response.end();
+            return;
+          }
+          try {
+            sendJson(response, 200, compute());
+          } catch (err) {
+            sendJson(response, 500, { error: err.message });
+          }
+        },
+      }),
+    );
+  }
+  return disposers;
+}
+module.exports = { mountPanel, PAGE };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "repository": {
     "type": "git",