dsh-xray 0.8.1 → 0.9.0

package/README.md

@@ -19,17 +19,53 @@
   <a href="./README.zh.md">🇨🇳 中文文档</a>
 </p>
 
-![dsh-xray demo](./docs/demo.svg)
+---
+
+Every plugin you mount quietly bills every LLM request: prompt sections, tool schemas, tokens. dsh-xray sits inside your running harness as an **X-Ray tab beside Chat and Trajectory** and itemizes that bill — per plugin, per entry, down to the exact text:
+
+![The X-Ray tab: every plugin's per-request context tax, attributed and ranked](./assets/tab-cost.webp)
+
+Unfold a plugin to see what it registered; click any entry to read the exact text it puts into every request:
+
+<table>
+<tr>
+<td width="50%">
+
+![A plugin unfolds into its registered entries](./assets/tab-expand.webp)
+
+</td>
+<td width="50%">
+
+![The raw text behind ~184 tokens, with a chars/tokens ruler](./assets/tab-entry.webp)
+
+</td>
+</tr>
+</table>
+
+Three clicks: plugin rollup → entry list → the actual words. The number stops being an estimate you trust and becomes a fact you checked.
 
 ---
 
 ## 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 --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** on every single request.
+
+**dsh-xray does.** And when the answer is "this plugin taxes every request and nothing depends on it" — the `deps` view confirms the disable is safe, one patch line removes it, and `attribute` verifies it took.
+
+---
+
+<p align="center">
+  <img src="./assets/section-context-tax.svg" width="100%" alt="Context Tax">
+</p>
+
+The cost view answers the question no other tool asks: **who put this in my context, and what does it cost?**
 
-**dsh-xray does.**
+- **Attribution** — every prompt section and tool schema is joined to the plugin that registered it, reconstructed live from the registries (ambiguous entries stay `unattributed`, never guessed).
+- **By-plugin rollup** — each plugin's per-request context tax: sections + schemas + tokens + share, ranked.
+- **Entry inspection** — `/xray/api/entry` returns any entry's live text with a chars/tokens ruler. Computed per request, never persisted.
+- **Explained UI** — every view opens with a one-line "what am I looking at"; terms carry plain-language tooltips; the whole tab is localized (English / 中文) through the host locale service.
 
-> Static commands work even when dsh cannot boot; `deps`/`health`/`cost`/`shadow` and the agent tool need the plugin mounted.
+The same data flows through three surfaces: the **X-Ray tab** (native GUI), the standalone **`/xray` page** (works even when the client-module pipeline it diagnoses is broken), and the **CLI**.
 
 ---
 
@@ -49,6 +85,12 @@ npx dsh-xray shadow      # services provided by multiple plugins
 npx dsh-xray audit       # static scan of out-of-tree plugins for sensitive touchpoints
 ```
 
+![dsh-xray demo](./docs/demo.svg)
+
+`attribute`, `conflicts`, and `snapshot` are fully static — they work even when dsh cannot boot. All commands take `--profile <name>` (default `web`) and `--json`; `diff` and `health` exit `1` on drift/unhealth, so they slot into CI.
+
+---
+
 <p align="center">
   <img src="./assets/section-features.svg" width="100%" alt="Features">
 </p>
@@ -61,56 +103,35 @@ npx dsh-xray audit       # static scan of out-of-tree plugins for sensitive touc
 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.
+Installed-but-inactive, uninstalled-but-lingering patch rows — including patch rows targeting ids that don't exist (dsh skips them silently).
 
 ### ⚡ 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.
+Export the effective composition as a lockfile; reproduce it elsewhere, diff against it later.
 
 </td>
 <td width="50%">
 
 ### 🌐 Service Dependency Graph
-Who provides and consumes each service; what cascades if you disable X.
+Who provides and consumes each service — and the **disable-cascade**: exactly which dependents go down 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.
+Per-plugin fiber lifecycle state, startup failures, pending injects, transition history.
 
-The package also ships a client half (`dsh.client` declaration + `exports["./client"]`): the host discovers it automatically and mounts an **X-ray tab beside Chat / Trajectory** in every session, rendering the same five views natively in the GUI with the host's design tokens. The standalone `/xray` page stays available as the degradation path — it only needs the web server, not the client-module pipeline it helps diagnose.
-
-![The /xray panel: deps view with the disable-cascade table](./assets/panel-deps.webp)
-
-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:
+### 👥 Service Shadowing
+Same-name registrations where a later writer silently wins — usually an intended override, occasionally a conflict.
 
 ### 🛡️ Capability Audit
-Heuristic static scan: network egress, shell, filesystem, env, eval.
+Heuristic static scan of out-of-tree plugins: network egress, shell, filesystem, env, eval.
 
 </td>
 </tr>
 </table>
 
+---
+
 <p align="center">
   <img src="./assets/section-agent.svg" width="100%" alt="Agent Tool">
 </p>
@@ -131,7 +152,8 @@ Mounted in the tree, dsh-xray registers an `xray_composition` tool (`view: summa
 
 - 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/`
+- The mounted plugin writes only under `$DSH_HOME/xray/` — entry text is served live, **never persisted**
+- The entry endpoint returns composition-layer text only, **never session messages**
 - See [SECURITY.md](./SECURITY.md)
 
 ---
@@ -148,7 +170,7 @@ Two ways to use it — they're independent:
 npx dsh-xray attribute        # requires Node >= 22
 ```
 
-**2. Mount the plugin** (adds the runtime commands, the `/xray` panel, and the agent tool):
+**2. Mount the plugin** (adds the runtime commands, the X-Ray tab, the `/xray` panel, and the agent tool):
 
 ```sh
 dsh plugin --profile web add dsh-xray
@@ -160,13 +182,12 @@ Verify it took:
 ```sh
 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
+# then open any session and click the X-Ray tab,
+# or http://localhost:3080/xray for the standalone 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 |
@@ -184,16 +205,16 @@ Diagnostic imaging for a running composition — complementary to [dsh-doctor](h
 
 | Feature | Category |
 | --- | --- |
+| Context-tax attribution & entry inspection | 💰 Optimization |
 | Layer attribution | 🔍 Inspection |
 | Declared vs. actual diff | 🔍 Inspection |
 | Conflict detection | 🔍 Inspection |
 | Composition snapshot | 📦 Export |
 | Service dependency graph | 🌐 Runtime |
 | Runtime health | 🌐 Runtime |
+| Service shadowing | 🌐 Runtime |
 | Agent self-introspection | 🤖 AI |
 | Capability audit | 🛡️ Security |
-| Service shadowing | 🌐 Runtime |
-| Context cost | 💰 Optimization |
 
 ---
 

package/README.zh.md

@@ -18,13 +18,59 @@
   <a href="./README.md">English</a>
 </p>
 
-![dsh-xray 演示](./docs/demo.svg)
+---
+
+你挂载的每个插件都在悄悄向每次 LLM 请求收费:prompt sections、工具 schema、token。dsh-xray 以 **与 Chat / Trajectory 并列的 X 光标签页** 长在你运行中的 harness 里,把这份账单逐项摊开——按插件、按条目,直到具体到每一个字:
+
+![X 光标签页:每个插件的每请求上下文税,已归因并排序](./assets/tab-cost.webp)
+
+展开插件看它注册了什么;点击任何条目,读它注入每次请求的原文:
+
+<table>
+<tr>
+<td width="50%">
+
+![插件展开为其注册的条目](./assets/tab-expand.webp)
+
+</td>
+<td width="50%">
+
+![~184 token 背后的原文,附字符/token 标尺](./assets/tab-entry.webp)
+
+</td>
+</tr>
+</table>
+
+三次点击:插件总账 → 条目清单 → 实际文字。数字不再是你被迫相信的估算,而是你亲手核对过的事实。
+
+---
+
+## 问题
 
-> 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
+`dsh --dump-config` 只给你原始组合树,插件面板只给你平铺列表。它们都不回答:这个插件**为什么**在这、停用它会**连带瘫掉什么**、它在每次请求里**悄悄消耗什么**。
 
-`dsh --dump-config` 只给你原始组合树,插件面板只给你平铺列表。它们都不回答:这个插件*为什么*在这、停用它会*连带瘫掉什么*、它在*悄悄消耗什么*。dsh-xray 回答这些。
+**dsh-xray 回答这些。** 当答案是"这个插件对每次请求收税、却没有任何东西依赖它"——`deps` 视图确认可以安全停用,一行 patch 移除它,`attribute` 验证生效。
 
-## CLI
+---
+
+<p align="center">
+  <img src="./assets/section-context-tax.svg" width="100%" alt="上下文税">
+</p>
+
+cost 视图回答一个别的工具都不问的问题:**这段上下文是谁放进来的、花掉我多少?**
+
+- **来源归因** —— 每个 prompt section 和工具 schema 都关联到注册它的插件,实时从 registry 重建(无法唯一归因的条目诚实标注 `unattributed`,绝不猜测)。
+- **按插件汇总** —— 每个插件的每请求上下文税:sections + schemas + tokens + 占比,排序呈现。
+- **条目原文查看** —— `/xray/api/entry` 返回任意条目的实时文本,附字符/token 标尺。按请求现算,绝不落盘。
+- **界面自解释** —— 每个视图开头一句"你在看什么";术语带白话提示;整个标签页通过宿主 locale 服务双语呈现(English / 中文)。
+
+同一份数据流经三个界面:**X 光标签页**(原生 GUI)、独立 **`/xray` 页面**(连它所诊断的 client-module 加载链路挂了都能用)、以及 **CLI**。
+
+---
+
+<p align="center">
+  <img src="./assets/section-cli.svg" width="100%" alt="CLI 命令">
+</p>
 
 ```sh
 npx dsh-xray attribute   # 每一行由哪层引入、之后被谁 patch 过
@@ -38,126 +84,139 @@ npx dsh-xray shadow      # 被多个插件同时提供的服务
 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` 的运行时快照。
-
-## 长什么样
+![dsh-xray 演示](./docs/demo.svg)
 
-启动树的每一行,归因到引入它的层——以及之后谁 patch 过它:
+`attribute`、`conflicts`、`snapshot` 是纯静态的——dsh 起不来时照样能跑。所有命令支持 `--profile <name>`(默认 `web`)和 `--json`;`diff` 与 `health` 在漂移/不健康时退出码 `1`,可直接进 CI。
 
-```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
-...
-```
+<p align="center">
+  <img src="./assets/section-features.svg" width="100%" alt="能力">
+</p>
 
-停用一个 provider 会连带瘫掉什么——从真实服务存储算出来,不是猜的:
+<table>
+<tr>
+<td width="50%">
 
-```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
-```
+### 🔍 层归因
+每个活跃插件来自哪一层:内核 bundle / profile 依赖 / `cordis.patch.yml` insert / repository 源。
 
-哪些字段有多个写者、谁静默赢了:
+### 📊 声明 vs 实际 diff
+装了但没生效、卸了但残留 patch 行——包括指向不存在 id 的 patch 行(dsh 会静默跳过)。
 
-```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)
-```
+### ⚡ 冲突检测
+多个插件 patch 同一配置行时,谁静默赢了。
 
-每次请求实际携带什么——assembly 时观测到的 prompt sections,与工具 schema 合并计价:
+### 📸 组合快照
+把当前生效组合导出为 lockfile,异地复现、事后对比。
 
-```console
-$ npx dsh-xray cost
-~1625 tokens: 1 tool schema(s) ~121 + 19 prompt section(s) ~1504
+</td>
+<td width="50%">
 
-# 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%    ███
-...
-```
+### 🌐 服务依赖图
+每个服务谁提供、谁消费——以及**停用级联**:停用 X 会连带瘫掉哪些依赖方。
 
-patch 行指向不存在的 id 时(dsh 静默跳过),`diff` 能抓到:
+### 💊 运行时健康
+每个插件的 fiber 生命周期状态、启动失败、等待中的注入、状态迁移史。
 
-```console
-$ npx dsh-xray diff
-orphan overrides (silently skipped) (1)
-  no-such-row in ~/.dsh/profiles/web/cordis.patch.yml
-```
+### 👥 服务遮蔽
+同名注册中后来者静默胜出——通常是有意覆盖,偶尔是冲突。
 
-## Agent 工具
+### 🛡️ 能力审计
+对 out-of-tree 插件的启发式静态扫描:网络外发、shell、文件系统、环境变量、eval。
 
-挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答"我有哪些能力 / 哪个插件提供 X / 为什么 Y 不可用"。
+</td>
+</tr>
+</table>
 
-## Web 面板
+---
 
-在 `dsh web` 中挂载后,插件在 **`/xray`** 提供零依赖面板——summary、health、deps(含停用级联表)、cost、shadow 五个视图,数据实时来自运行中的组合树;`/xray/api/*` 提供同源 JSON。
+<p align="center">
+  <img src="./assets/section-agent.svg" width="100%" alt="Agent 工具">
+</p>
 
-包同时携带 client 半(`dsh.client` 声明 + `exports["./client"]`):宿主自动发现并在每个会话中挂载 **与 Chat / Trajectory 并列的 X-ray 标签页**,用宿主设计变量原生渲染同样五个视图。独立的 `/xray` 页面保留为降级通道——它只依赖 web 服务器,不依赖它所诊断的 client-module 加载链路。
+挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答:
 
-![/xray 面板:deps 视图与停用级联表](./assets/panel-deps.webp)
+> *"我有哪些能力?" / "哪个插件提供 X?" / "为什么 Y 不可用?"*
 
-## 安全立场
+——关于它自己。
 
-dsh-xray 只读不执行。patch 文件里的 loader `!!js` 表达式解析为不透明标记、绝不求值;CLI 从不执行插件代码(`audit` 是对源码文本的模式扫描);挂载的插件只写 `$DSH_HOME/xray/` 目录。详见 [SECURITY.md](./SECURITY.md)。
+---
 
-## 能力
+<p align="center">
+  <img src="./assets/section-safety.svg" width="100%" alt="安全立场">
+</p>
 
-对运行中组合树的诊断成像——与 [dsh-doctor](https://www.npmjs.com/package/dsh-doctor)(救援与恢复)互补。
+**dsh-xray 只读,不执行。**
 
-已交付:
+- patch 文件里的 loader `!!js` 表达式解析为不透明标记,**绝不求值**
+- CLI **从不执行**插件代码(`audit` 是对源码文本的模式扫描)
+- 挂载的插件只写 `$DSH_HOME/xray/` 目录——条目原文实时返回,**绝不落盘**
+- entry 端点只返回组合层文本,**绝不返回会话消息**
+- 详见 [SECURITY.md](./SECURITY.md)
 
-- **来源归因** — 每个活跃插件来自哪一层:内核 bundle / profile 依赖 / `cordis.patch.yml` insert / repository 源
-- **声明 vs 实际 diff** — 装了但没生效、卸了但残留 patch 行
-- **冲突检测** — 多个插件 patch 同一配置行时,谁静默赢了
-- **组合快照** — 把当前生效组合导出为 lockfile;`--against` 对比漂移
-- **服务依赖图** — 每个服务谁提供、谁消费;停用 X 会级联影响什么(`deps`)
-- **运行时健康** — 每个插件的 fiber 生命周期状态、启动失败、状态迁移史(`health`)
-- **Agent 自省** — `xray_composition` 工具让 agent 检视自己的能力集
-- **能力审计** — 对 out-of-tree 插件的启发式静态扫描:网络外发、shell、文件系统、环境变量、动态求值(`audit`)
-- **服务重名检测** — 被多个插件同时提供的服务,及每插件工具/命令注册数(`shadow`)
-- **上下文成本** — prompt sections(观测自 system-prompt/assemble)+ 工具 schema 的估算 token 占用(`cost`)
-- **Web 面板** — `/xray` 五视图,零依赖零构建
+---
 
-## 安装
+<p align="center">
+  <img src="./assets/section-install.svg" width="100%" alt="安装">
+</p>
 
-两条使用路径,互相独立:
+两种用法,彼此独立:
 
-**1. 只用静态 CLI**(不装进 dsh;dsh 起不来时也能用):
+**1. 只用静态 CLI**(不装进 dsh;dsh 起不来时照样能用):
 
 ```sh
 npx dsh-xray attribute        # 需要 Node >= 22
 ```
 
-**2. 挂载插件**(解锁运行时命令、`/xray` 面板和 agent 工具):
+**2. 挂载插件**(解锁运行时命令、X 光标签页、`/xray` 面板和 agent 工具):
 
 ```sh
 dsh plugin --profile web add dsh-xray
-# bundle 插件重启后生效——重启 dsh web
+# bundle 插件下次启动生效——重启 dsh web
 ```
 
-验证装好了:
+验证生效:
 
 ```sh
-dsh --profile web --dump-config | grep dsh-xray   # 组合树里有这一行
-npx dsh-xray health                               # 能读到运行时快照
-# 然后打开 http://localhost:3080/xray 看实时面板
+dsh --profile web --dump-config | grep dsh-xray   # 组合树中出现该行
+npx dsh-xray health                               # 读取运行时快照
+# 然后打开任意会话点 X 光标签页,
+# 或访问 http://localhost:3080/xray 看独立面板
 ```
 
 卸载:`dsh plugin --profile web remove dsh-xray`。
 
-## 许可证
+| 命令 | 行为 |
+| --- | --- |
+| `diff` | 两棵树不一致时退出码 `1` |
+| `health` | 有插件不健康时退出码 `1` |
+| `attribute`、`conflicts`、`snapshot` | 纯静态——dsh 起不来时照样能跑 |
+| `deps`、`health` | 读取 `$DSH_HOME/xray/runtime.json` 运行时快照 |
+
+---
+
+<p align="center">
+  <img src="./assets/section-capabilities.svg" width="100%" alt="能力总表">
+</p>
+
+对运行中组合树的诊断成像——与 [dsh-doctor](https://www.npmjs.com/package/dsh-doctor)(救援与恢复)互补。
+
+| 能力 | 类别 |
+| --- | --- |
+| 上下文税归因 & 条目原文查看 | 💰 优化 |
+| 层归因 | 🔍 检视 |
+| 声明 vs 实际 diff | 🔍 检视 |
+| 冲突检测 | 🔍 检视 |
+| 组合快照 | 📦 导出 |
+| 服务依赖图 | 🌐 运行时 |
+| 运行时健康 | 🌐 运行时 |
+| 服务遮蔽 | 🌐 运行时 |
+| Agent 自省 | 🤖 AI |
+| 能力审计 | 🛡️ 安全 |
+
+---
+
+## 许可
 
-MIT
+[MIT](./LICENSE)

package/assets/hero.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="900" height="360" viewBox="0 0 900 360">
+  <title>dsh-xray — X-ray for your DeepSeek Harness</title>
   <defs>
     <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
       <stop offset="0%" style="stop-color:#0a0e17"/>

package/assets/section-agent.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="260" height="60" viewBox="0 0 260 60">
+  <title>Agent Tool</title>
   <defs>
     <linearGradient id="line" x1="0%" y1="0%" x2="100%" y2="0%">
       <stop offset="0%" style="stop-color:#00d4aa;stop-opacity:0"/>

package/assets/section-capabilities.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="288" height="60" viewBox="0 0 288 60">
+  <title>Capabilities</title>
   <defs>
     <linearGradient id="line" x1="0%" y1="0%" x2="100%" y2="0%">
       <stop offset="0%" style="stop-color:#00d4aa;stop-opacity:0"/>

package/assets/section-cli.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="288" height="60" viewBox="0 0 288 60">
+  <title>CLI Commands</title>
   <defs>
     <linearGradient id="line" x1="0%" y1="0%" x2="100%" y2="0%">
       <stop offset="0%" style="stop-color:#00d4aa;stop-opacity:0"/>

package/assets/section-context-tax.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="288" height="60" viewBox="0 0 288 60">
+  <title>Context Tax</title>
+  <defs>
+    <linearGradient id="line" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#00d4aa;stop-opacity:0"/>
+      <stop offset="50%" style="stop-color:#00d4aa;stop-opacity:0.4"/>
+      <stop offset="100%" style="stop-color:#00d4aa;stop-opacity:0"/>
+    </linearGradient>
+  </defs>
+  <line x1="0" y1="30" x2="288" y2="30" stroke="url(#line)" stroke-width="1"/>
+  <g transform="translate(144, 30)">
+    <rect x="-114" y="-16" width="228" height="32" rx="16" fill="#0a0e17" stroke="#1e293b" stroke-width="1"/>
+    <text x="0" y="5" text-anchor="middle" fill="#00d4aa" font-family="'SF Mono', 'Fira Code', monospace" font-size="14" font-weight="600" letter-spacing="1">▸ CONTEXT TAX</text>
+  </g>
+</svg>

package/assets/section-features.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="232" height="60" viewBox="0 0 232 60">
+  <title>Features</title>
   <defs>
     <linearGradient id="line" x1="0%" y1="0%" x2="100%" y2="0%">
       <stop offset="0%" style="stop-color:#00d4aa;stop-opacity:0"/>

package/assets/section-install.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="218" height="60" viewBox="0 0 218 60">
+  <title>Install</title>
   <defs>
     <linearGradient id="line" x1="0%" y1="0%" x2="100%" y2="0%">
       <stop offset="0%" style="stop-color:#00d4aa;stop-opacity:0"/>

package/assets/section-safety.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="302" height="60" viewBox="0 0 302 60">
+  <title>Safety Stance</title>
   <defs>
     <linearGradient id="line" x1="0%" y1="0%" x2="100%" y2="0%">
       <stop offset="0%" style="stop-color:#00d4aa;stop-opacity:0"/>

package/docs/demo.svg

@@ -1,4 +1,5 @@
 <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">
+  <title>dsh-xray CLI demo</title>
 <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>

package/lib/client.js

@@ -68,7 +68,7 @@ window.__ModuleLoader__.load({
     //#endregion
 
     //#region tiny view primitives
-    const VIEWS = ['summary', 'health', 'deps', 'cost', 'shadow'];
+    const VIEWS = ['summary', 'health', 'deps', 'cost', 'shadow', 'skills'];
     const NS = 'xray';
 
     /** English messages (also the key vocabulary; zh mirrors every key). */
@@ -150,6 +150,25 @@ window.__ModuleLoader__.load({
       'cost.noAssembly': 'no prompt assembly observed yet — send one agent message first',
       'cost.unattributed': 'unattributed',
       'shadow.clean': 'no service is provided by more than one plugin',
+      'intro.skills':
+        'What each skill costs: its catalog line rides every request once any model-invocable skill exists; its body is billed only when loaded. Pricing only — to enable/disable skills, use a skill manager.',
+      'tip.catalog':
+        "Tokens of this skill's line in the durable session catalog, carried on every request",
+      'tip.body':
+        'Tokens of the full rendered skill body, billed per load and then resident in history',
+      'tip.invocable':
+        'Whether the model may load this skill itself; user-only skills stay out of the catalog',
+      'col.skill': 'skill',
+      'col.provider2': 'provider',
+      'col.catalog': 'catalog',
+      'col.body': 'body',
+      'col.invocable': 'invocable',
+      'skills.summary':
+        '{count} skill(s), {invocable} model-invocable · resident catalog ~{resident} tokens (~{entries} entries + ~{framing} framing) on every request',
+      'skills.none':
+        'no skill observation yet — the skills service is absent or discovery has not run',
+      'skills.yes': 'yes',
+      'skills.userOnly': 'user-only',
       'entry.loading': 'loading entry…',
       'entry.stats': '{chars} chars · ~{tokens} tokens ({estimator})',
       'entry.close': 'close',
@@ -230,6 +249,21 @@ window.__ModuleLoader__.load({
       'cost.noAssembly': '尚未观测到 prompt 装配——先发送一条 agent 消息',
       'cost.unattributed': '未归因',
       'shadow.clean': '没有服务被多个插件同时提供',
+      'intro.skills':
+        '每个 skill 的价格:只要存在模型可调用的 skill,它的 catalog 行就随每次请求发送;正文只在加载时计费。这里只计价——启用/禁用请使用 skill 管理器。',
+      'tip.catalog': '该 skill 在持久会话 catalog 中那一行的 token,每次请求都携带',
+      'tip.body': '完整渲染正文的 token,每次加载时计费,之后驻留在历史中',
+      'tip.invocable': '模型能否自行加载该 skill;仅用户可调用的 skill 不进入 catalog',
+      'col.skill': 'skill',
+      'col.provider2': '提供者',
+      'col.catalog': 'catalog 行',
+      'col.body': '正文',
+      'col.invocable': '可调用',
+      'skills.summary':
+        '{count} 个 skill,{invocable} 个模型可调用 · 常驻 catalog 约 {resident} tokens(条目约 {entries} + 框架约 {framing}),每次请求都携带',
+      'skills.none': '尚无 skill 观测——skills 服务缺失或发现未运行',
+      'skills.yes': '是',
+      'skills.userOnly': '仅用户',
       'entry.loading': '正在加载条目…',
       'entry.stats': '{chars} 字符 · 约 {tokens} tokens({estimator})',
       'entry.close': '关闭',
@@ -633,6 +667,40 @@ window.__ModuleLoader__.load({
               )
             : null,
         ),
+
+      skills: (d, t) =>
+        !d.available
+          ? h('p', { className: 'xray-muted' }, t('skills.none'))
+          : h(
+              react.Fragment,
+              null,
+              h(
+                'p',
+                null,
+                fill(t('skills.summary'), {
+                  count: d.totals.count,
+                  invocable: d.totals.invocable,
+                  resident: d.totals.residentTokens,
+                  entries: d.totals.catalogEntryTokens,
+                  framing: d.totals.catalogOverheadTokens,
+                }),
+              ),
+              h(Table, {
+                t,
+                headers: ['skill', 'provider2', 'catalog', 'body', 'invocable'],
+                rows: d.skills.map((s) =>
+                  Row(s.name, [
+                    s.name,
+                    { cls: 'xray-muted', text: s.provider ?? '—' },
+                    { cls: 'xray-num', text: `~${s.catalogTokens}` },
+                    { cls: 'xray-num', text: s.bodyTokens === null ? '—' : `~${s.bodyTokens}` },
+                    s.modelInvocable
+                      ? h('span', { className: 'xray-ok' }, t('skills.yes'))
+                      : h('span', { className: 'xray-muted' }, t('skills.userOnly')),
+                  ]),
+                ),
+              }),
+            ),
     };
     //#endregion
 

package/lib/collect/runtime.js

@@ -207,10 +207,75 @@ function snapshotEntry(ctx, kind, name) {
   }
 }
 
+/**
+ * Estimate every skill's context cost from the live skills registry.
+ * Async (discovery may hit the filesystem); callers cache the result.
+ *
+ * Two prices per skill:
+ * - `catalogTokens` — its line in the durable session catalog
+ *   (`- \`name\`: description`, description normalized/truncated the way
+ *   dsh-tool-skill renders it). This line rides EVERY request once any
+ *   model-invocable skill exists.
+ * - `bodyTokens` — the full rendered body, billed only when the skill is
+ *   loaded (per call, then resident in history). Read via skills.get;
+ *   unreadable bodies report null rather than a guess.
+ *
+ * `catalogOverheadTokens` prices the fixed catalog framing (the
+ * system-reminder prose around the entries).
+ */
+async function snapshotSkills(ctx, options = {}) {
+  const skills = ctx.get?.('skills');
+  if (!skills?.list) return null;
+  const maxLength = options.descriptionMaxLength ?? 120;
+  const catalogLine = (name, description) => {
+    const normalized = String(description ?? '')
+      .replaceAll(/\s+/g, ' ')
+      .trim();
+    const truncated =
+      normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3)}...`;
+    return `- \`${name}\`: ${truncated}`;
+  };
+  // The fixed framing dsh-tool-skill wraps around the entry lines.
+  const FRAMING =
+    "<system-reminder>\nA skill is a reusable set of task-specific instructions. The following skills are available in this session:\n\n<available_skills>\n</available_skills>\n\nIf the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.\n</system-reminder>";
+  try {
+    const list = await skills.list(options.lookup ?? {});
+    const rows = [];
+    for (const summary of list) {
+      const line = catalogLine(summary.name, summary.description);
+      const row = {
+        name: summary.name,
+        provider: summary.provider ?? null,
+        source: summary.source ?? null,
+        modelInvocable: summary.invocation?.modelInvocable !== false,
+        catalogLine: line,
+        catalogTokens: estimateTokens(line),
+        bodyTokens: null,
+      };
+      try {
+        const full = await skills.get(summary.name, options.lookup ?? {});
+        if (full?.content !== undefined) row.bodyTokens = estimateTokens(String(full.content));
+        else if (typeof full?.body === 'string') row.bodyTokens = estimateTokens(full.body);
+      } catch {
+        /* body unreadable: null, never a guess */
+      }
+      rows.push(row);
+    }
+    return {
+      capturedAt: new Date().toISOString(),
+      catalogOverheadTokens: estimateTokens(FRAMING),
+      skills: rows,
+    };
+  } catch {
+    return null;
+  }
+}
+
 module.exports = {
   snapshotRegistry,
   snapshotTools,
   snapshotEntry,
+  snapshotSkills,
   injectNames,
   provideNames,
   stateName,

package/lib/index.js

@@ -4,11 +4,12 @@ const os = require('node:os');
 const {
   snapshotRegistry,
   snapshotEntry,
+  snapshotSkills,
   stateName,
   estimateTokens,
 } = require('./collect/runtime.js');
 const { installSectionAttribution } = require('./collect/attribution.js');
-const { serviceGraph, health, shadowing, contextCost } = require('./model.js');
+const { serviceGraph, health, shadowing, contextCost, skillCost } = require('./model.js');
 
 const name = 'dsh-xray';
 
@@ -34,6 +35,26 @@ function apply(ctx) {
   const transitions = new Map(); // plugin name -> [{state, at}] ring buffer
   let lastAssembly = null; // latest system-prompt assembly observation
   let attribution = null; // section name -> plugin name (live table)
+  let skillCatalog = null; // latest skill-cost observation (async, throttled)
+  let skillRefreshing = false;
+  const refreshSkills = (lookup) => {
+    // Discovery hits the filesystem and is scope/cwd-sensitive: the
+    // filesystem provider resolves user/project roots from the viewing
+    // agent, so a bare-context list() sees nothing. We piggyback on the
+    // assemble waterfall, whose context carries the agent scope (and the
+    // session cwd through it). One refresh in flight; failures keep
+    // last-good state.
+    if (skillRefreshing) return;
+    skillRefreshing = true;
+    snapshotSkills(ctx, { lookup })
+      .then((observed) => {
+        if (observed) skillCatalog = observed;
+      })
+      .catch(() => {})
+      .finally(() => {
+        skillRefreshing = false;
+      });
+  };
 
   let timer = null;
   const writeSnapshot = () => {
@@ -44,6 +65,7 @@ function apply(ctx) {
       snap.promptAssembly = lastAssembly;
       snap.sectionOwners = attribution ? Object.fromEntries(attribution.table) : {};
       snap.toolOwners = attribution ? Object.fromEntries(attribution.toolTable) : {};
+      snap.skillCatalog = skillCatalog;
       fs.mkdirSync(dir, { recursive: true });
       const tmp = `${file}.tmp`;
       fs.writeFileSync(tmp, JSON.stringify(snap, null, 2));
@@ -73,7 +95,7 @@ function apply(ctx) {
     // 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 disposeAssemble = ctx.on('system-prompt/assemble', async (assembly, context, next) => {
       const result = await next();
       try {
         lastAssembly = {
@@ -86,10 +108,20 @@ function apply(ctx) {
       } catch {
         /* observation must never break assembly */
       }
+      try {
+        const agent = context?.agent ?? context?.scope;
+        refreshSkills({
+          ...(context?.scope !== undefined ? { scope: context.scope } : {}),
+          ...(agent?.session?.header?.cwd !== undefined ? { cwd: agent.session.header.cwd } : {}),
+        }); // piggyback: one throttled async catalog refresh per assembly, in the assembling agent's view
+      } catch {
+        /* skill observation must never break assembly */
+      }
       schedule();
       return result;
     });
     schedule(); // initial snapshot
+    refreshSkills(); // initial skill-cost observation
     // Section attribution: diff-based name->plugin table over
     // system-prompt/change (see collect/attribution.js for the strategy).
     attribution = installSectionAttribution(ctx);
@@ -120,6 +152,7 @@ function apply(ctx) {
         snap.promptAssembly = lastAssembly;
         snap.sectionOwners = attribution ? Object.fromEntries(attribution.table) : {};
         snap.toolOwners = attribution ? Object.fromEntries(attribution.toolTable) : {};
+        snap.skillCatalog = skillCatalog;
         return snap;
       };
       wctx.effect(
@@ -141,6 +174,7 @@ function apply(ctx) {
               health: () => health(freshSnap()),
               cost: () => contextCost(freshSnap()),
               shadow: () => shadowing(freshSnap()),
+              skills: () => skillCost(freshSnap()),
             },
             // Entry text is computed per request from the live registries and
             // never persisted — the audit answer to "what exactly is ~N tokens?".
@@ -185,7 +219,7 @@ function apply(ctx) {
           parameters: {
             view: {
               type: 'string',
-              description: 'summary | deps | health | cost | shadow (default summary)',
+              description: 'summary | deps | health | cost | shadow | skills (default summary)',
             },
           },
           output: {
@@ -198,10 +232,12 @@ function apply(ctx) {
             snap.promptAssembly = lastAssembly;
             snap.sectionOwners = attribution ? Object.fromEntries(attribution.table) : {};
             snap.toolOwners = attribution ? Object.fromEntries(attribution.toolTable) : {};
+            snap.skillCatalog = skillCatalog;
             if (args.view === 'deps') return serviceGraph(snap);
             if (args.view === 'health') return health(snap);
             if (args.view === 'cost') return contextCost(snap);
             if (args.view === 'shadow') return shadowing(snap);
+            if (args.view === 'skills') return skillCost(snap);
             return {
               plugins: snap.plugins.length,
               unhealthy: health(snap).unhealthy.length,

package/lib/model.js

@@ -340,6 +340,43 @@ function contextCost(snap) {
   };
 }
 
+/** F10: skill context cost — the catalog line every request carries per
+ * skill, plus each skill's on-load body size. Read-only companion to the
+ * ecosystem's skill managers: xray prices, it never toggles. */
+function skillCost(snap) {
+  const observed = snap.skillCatalog;
+  if (!observed) return { available: false, skills: [], totals: null, capturedAt: snap.capturedAt };
+  const rows = observed.skills
+    .slice()
+    .sort((a, b) => b.catalogTokens - a.catalogTokens)
+    .map((s) => ({
+      name: s.name,
+      provider: s.provider,
+      source: s.source,
+      modelInvocable: s.modelInvocable,
+      catalogTokens: s.catalogTokens,
+      bodyTokens: s.bodyTokens,
+    }));
+  const invocable = rows.filter((s) => s.modelInvocable);
+  const catalogEntryTokens = invocable.reduce((sum, s) => sum + s.catalogTokens, 0);
+  return {
+    available: true,
+    skills: rows,
+    totals: {
+      count: rows.length,
+      invocable: invocable.length,
+      // Only model-invocable skills enter the durable catalog; its framing
+      // is a fixed one-off on top of the per-skill lines.
+      catalogEntryTokens,
+      catalogOverheadTokens: observed.catalogOverheadTokens,
+      residentTokens:
+        invocable.length > 0 ? catalogEntryTokens + observed.catalogOverheadTokens : 0,
+    },
+    observedAt: observed.capturedAt,
+    capturedAt: snap.capturedAt,
+  };
+}
+
 module.exports = {
   replayLayers,
   attribute,
@@ -350,4 +387,5 @@ module.exports = {
   health,
   shadowing,
   contextCost,
+  skillCost,
 };

package/lib/panel.js

@@ -38,7 +38,7 @@ const PAGE = `<!doctype html>
 <div id="status"></div>
 <div id="content"></div>
 <script>
-const views = ['summary', 'health', 'deps', 'cost', 'shadow'];
+const views = ['summary', 'health', 'deps', 'cost', 'shadow', 'skills'];
 const esc = (s) => String(s ?? '').replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
 const escAttr = (s) => esc(s).replace(/"/g, '&quot;');
 
@@ -49,6 +49,7 @@ const INTRO = {
   deps: 'Who provides and consumes each service. The disable-cascade table answers: if I disable this plugin, which dependents stop working with it?',
   cost: 'What every LLM request carries before your message: prompt sections + tool schemas, attributed to the plugin that registered each. "By plugin" is each plugin\\'s per-request context tax.',
   shadow: 'Same-name registrations. A service provided by two plugins means one silently wins — usually intended (an override), occasionally a conflict.',
+  skills: 'What each skill costs: its catalog line rides every request once any model-invocable skill exists; its body is billed only when loaded. Pricing only — to enable/disable skills, use a skill manager.',
 };
 
 // Hover glossary: term -> plain-language meaning (native title tooltips).
@@ -65,6 +66,9 @@ const TIPS = {
   registrations: 'How many tools/commands this plugin registered on the shared registries',
   sections: 'Prompt sections this plugin contributes to the system prompt',
   tools: 'Tool schemas this plugin registers (each costs context on every request)',
+  catalog: 'Tokens of this skill's line in the durable session catalog, carried on every request',
+  body: 'Tokens of the full rendered skill body, billed per load and then resident in history',
+  invocable: 'Whether the model may load this skill itself; user-only skills stay out of the catalog',
 };
 const th = (h) => '<th' + (TIPS[h] ? ' title="' + escAttr(TIPS[h]) + '"' : '') + '>' + esc(h) + '</th>';
 const intro = (v) => '<p class="muted" style="margin:0 0 10px">' + INTRO[v] + '</p>';
@@ -166,6 +170,17 @@ const renderers = {
     }
     return html;
   },
+  skills(d) {
+    if (!d.available) return '<p class="muted">no skill observation yet — the skills service is absent or discovery has not run</p>';
+    let html = '<p>' + d.totals.count + ' skill(s), ' + d.totals.invocable + ' model-invocable · resident catalog ~'
+      + d.totals.residentTokens + ' tokens (' + '~' + d.totals.catalogEntryTokens + ' entries + ~'
+      + d.totals.catalogOverheadTokens + ' framing) on every request</p>';
+    html += table(['skill', 'provider', 'catalog', 'body', 'invocable'], d.skills.map((s) =>
+      '<tr><td>' + esc(s.name) + '</td><td class="muted">' + esc(s.provider ?? '—')
+      + '</td><td class="num">~' + s.catalogTokens + '</td><td class="num">' + (s.bodyTokens === null ? '—' : '~' + s.bodyTokens)
+      + '</td><td>' + (s.modelInvocable ? '<span class="ok">yes</span>' : '<span class="muted">user-only</span>') + '</td></tr>'));
+    return html;
+  },
 };
 
 async function render() {

package/package.json

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