dsh-xray 0.3.0 → 0.3.2

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 (3) hide show
  1. package/README.md +51 -0
  2. package/README.zh.md +51 -0
  3. package/package.json +12 -3
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # dsh-xray
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/dsh-xray)](https://www.npmjs.com/package/dsh-xray)
4
+ [![CI](https://github.com/alloevil/dsh-xray/actions/workflows/check.yml/badge.svg)](https://github.com/alloevil/dsh-xray/actions/workflows/check.yml)
5
+ [![license](https://img.shields.io/npm/l/dsh-xray)](./LICENSE)
6
+
3
7
  X-ray for your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — see what's actually loaded, why, and what it costs you.
4
8
 
5
9
  [中文](./README.zh.md)
@@ -24,10 +28,57 @@ npx dsh-xray audit # static scan of out-of-tree plugins for sensitive touc
24
28
 
25
29
  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`.
26
30
 
31
+ ## What it looks like
32
+
33
+ Every row of the booted tree, attributed to the layer that introduced it — and who patched it since:
34
+
35
+ ```console
36
+ $ npx dsh-xray attribute
37
+ # 130 rows in profile "web"
38
+
39
+ timer @deepseek-ai/dsh-base
40
+ hmr @deepseek-ai/dsh-base ← patched by @deepseek-ai/dsh-web-app [disabled]
41
+ llm @deepseek-ai/dsh-base
42
+ session-query-sqlite @deepseek-ai/dsh-base ← patched by @deepseek-ai/dsh-web-app
43
+ ...
44
+ ```
45
+
46
+ What breaks if you disable a provider — computed from the live service store, not guesses:
47
+
48
+ ```console
49
+ $ npx dsh-xray deps
50
+ # disable-cascade (transitive consumers of each provider):
51
+ Loader → 5 plugin(s): AgentPresets, ClientModuleRegistry, Hmr, Include, PluginInventoryGateway
52
+ TimerService → 1 plugin(s): Hmr
53
+ SessionProjectionRegistry → 1 plugin(s): SessionProjectionCache
54
+ ```
55
+
56
+ Which fields have multiple writers, and who silently wins:
57
+
58
+ ```console
59
+ $ npx dsh-xray conflicts
60
+ session-query-sqlite
61
+ .config: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app (winner: @deepseek-ai/dsh-web-app)
62
+ tool-bash
63
+ .disabled: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app (winner: @deepseek-ai/dsh-web-app)
64
+ ```
65
+
66
+ And when a patch row targets an id that doesn't exist (dsh skips it silently), `diff` catches it:
67
+
68
+ ```console
69
+ $ npx dsh-xray diff
70
+ orphan overrides (silently skipped) (1)
71
+ no-such-row in ~/.dsh/profiles/web/cordis.patch.yml
72
+ ```
73
+
27
74
  ## Agent tool
28
75
 
29
76
  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.
30
77
 
78
+ ## Safety stance
79
+
80
+ 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), and the mounted plugin writes only under `$DSH_HOME/xray/`. See [SECURITY.md](./SECURITY.md).
81
+
31
82
  ## Capabilities
32
83
 
33
84
  Diagnostic imaging for a running composition — complementary to [dsh-doctor](https://www.npmjs.com/package/dsh-doctor) (rescue & recovery).
package/README.zh.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # dsh-xray
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/dsh-xray)](https://www.npmjs.com/package/dsh-xray)
4
+ [![CI](https://github.com/alloevil/dsh-xray/actions/workflows/check.yml/badge.svg)](https://github.com/alloevil/dsh-xray/actions/workflows/check.yml)
5
+ [![license](https://img.shields.io/npm/l/dsh-xray)](./LICENSE)
6
+
3
7
  给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 拍 X 光——看清到底加载了什么、为什么在那、以及它悄悄花掉了你什么。
4
8
 
5
9
  [English](./README.md)
@@ -24,10 +28,57 @@ npx dsh-xray audit # 对 out-of-tree 插件做敏感触点静态扫描
24
28
 
25
29
  所有命令支持 `--profile <name>`(默认 `web`)和 `--json`。`diff` 在两棵树不一致时退出码 `1`;`health` 在有插件不健康时退出码 `1`。`attribute`、`conflicts`、`snapshot` 是纯静态的:dsh 起不来时照样能跑。`deps` 和 `health` 读取已挂载插件维护在 `$DSH_HOME/xray/runtime.json` 的运行时快照。
26
30
 
31
+ ## 长什么样
32
+
33
+ 启动树的每一行,归因到引入它的层——以及之后谁 patch 过它:
34
+
35
+ ```console
36
+ $ npx dsh-xray attribute
37
+ # 130 rows in profile "web"
38
+
39
+ timer @deepseek-ai/dsh-base
40
+ hmr @deepseek-ai/dsh-base ← patched by @deepseek-ai/dsh-web-app [disabled]
41
+ llm @deepseek-ai/dsh-base
42
+ session-query-sqlite @deepseek-ai/dsh-base ← patched by @deepseek-ai/dsh-web-app
43
+ ...
44
+ ```
45
+
46
+ 停用一个 provider 会连带瘫掉什么——从真实服务存储算出来,不是猜的:
47
+
48
+ ```console
49
+ $ npx dsh-xray deps
50
+ # disable-cascade (transitive consumers of each provider):
51
+ Loader → 5 plugin(s): AgentPresets, ClientModuleRegistry, Hmr, Include, PluginInventoryGateway
52
+ TimerService → 1 plugin(s): Hmr
53
+ SessionProjectionRegistry → 1 plugin(s): SessionProjectionCache
54
+ ```
55
+
56
+ 哪些字段有多个写者、谁静默赢了:
57
+
58
+ ```console
59
+ $ npx dsh-xray conflicts
60
+ session-query-sqlite
61
+ .config: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app (winner: @deepseek-ai/dsh-web-app)
62
+ tool-bash
63
+ .disabled: @deepseek-ai/dsh-base → @deepseek-ai/dsh-web-app (winner: @deepseek-ai/dsh-web-app)
64
+ ```
65
+
66
+ patch 行指向不存在的 id 时(dsh 静默跳过),`diff` 能抓到:
67
+
68
+ ```console
69
+ $ npx dsh-xray diff
70
+ orphan overrides (silently skipped) (1)
71
+ no-such-row in ~/.dsh/profiles/web/cordis.patch.yml
72
+ ```
73
+
27
74
  ## Agent 工具
28
75
 
29
76
  挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答"我有哪些能力 / 哪个插件提供 X / 为什么 Y 不可用"。
30
77
 
78
+ ## 安全立场
79
+
80
+ dsh-xray 只读不执行。patch 文件里的 loader `!!js` 表达式解析为不透明标记、绝不求值;CLI 从不执行插件代码(`audit` 是对源码文本的模式扫描);挂载的插件只写 `$DSH_HOME/xray/` 目录。详见 [SECURITY.md](./SECURITY.md)。
81
+
31
82
  ## 能力
32
83
 
33
84
  对运行中组合树的诊断成像——与 [dsh-doctor](https://www.npmjs.com/package/dsh-doctor)(救援与恢复)互补。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-xray",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -32,7 +32,8 @@
32
32
  "test": "node --test tests/*.spec.js",
33
33
  "lint": "biome check .",
34
34
  "format": "biome check --write .",
35
- "check": "biome check . && node --test tests/*.spec.js"
35
+ "check": "biome check . && node --test tests/*.spec.js",
36
+ "coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 tests/*.spec.js"
36
37
  },
37
38
  "keywords": [
38
39
  "dsh-plugin",
@@ -41,7 +42,14 @@
41
42
  "cordis",
42
43
  "diagnostics",
43
44
  "introspection",
44
- "plugin-tree"
45
+ "plugin-tree",
46
+ "dependency-graph",
47
+ "observability",
48
+ "audit",
49
+ "security-scan",
50
+ "token-cost",
51
+ "lockfile",
52
+ "troubleshooting"
45
53
  ],
46
54
  "dsh": {
47
55
  "bundle": {
@@ -54,6 +62,7 @@
54
62
  "engines": {
55
63
  "node": ">=22"
56
64
  },
65
+ "packageManager": "pnpm@10.28.2",
57
66
  "publishConfig": {
58
67
  "registry": "https://registry.npmjs.org/",
59
68
  "access": "public"