@twinsearth/dsh-2xray 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 — 2026-10-29
+
+### 新增
+
+- **插件设置页表单**：导出 Schemastery `Config`，在 DSH 插件页可直接编辑启用开关、vless 分享链接、xray 路径、本地端口、takeover、功能探测与控制面开关；保存后写入 profile patch，重启 DSH 生效。高级配置（`nodes`、`routing`、`noProxy` 等）由 Schemastery 原样保留。
+- **左侧菜单「2Xray」**：插件标签下方新增黑色地球图标入口，主面板内置二维码图片识别、屏幕共享扫码与链接复制。
+- **二维码导入工具** `tools/scanner.html`：浏览器打开后可粘贴/复制链接、选择二维码图片、或共享屏幕实时扫码；优先用 `BarcodeDetector`，不可用时回退到内置 jsQR。
+
+### 说明
+
+- `Config` 的字段全部为 volatile；volatile-only 变更不会重挂插件，插件会记录「重启 DSH 后生效」。
+- 设置页内的原生扫码按钮仍待客户端半边，当前扫码入口是 `tools/scanner.html`（结果复制回设置页）。
+
 ## 0.1.1 — 2026-10-29
 
 ### 修复

package/README.md

@@ -177,6 +177,24 @@ bundle 自带的 `cordis.patch.yml` 默认 `enabled: false`，避免安装即报
 - API 入站只绑 `127.0.0.1`，但**无认证**：本机任意进程可查统计或切节点。需要更强隔离时用随机端口，或关闭 `control.enabled` 只保留静态多出站。
 - `stats` 计数器是**自进程启动以来的累计值**，不是速率；速率需要调用方自行差分。
 
+## 界面入口：设置页 + 左侧 2Xray 面板
+
+v0.2.0 提供两个入口，互不替代：
+
+1. **插件设置页**（设置 → 插件 → Xray 代理）：Schemastery 表单，可编辑
+   `启用`、`分享链接 (vless://)`、`xray 路径`、`本地端口`、`takeover`、`功能探测`、`控制面`。
+   保存后写入 profile patch，**重启 DSH 生效**。
+2. **左侧菜单「2Xray」**（插件标签下方，黑色地球图标）：内含
+   二维码图片识别、屏幕共享扫码、链接复制；识别后复制到设置页的「分享链接」保存。
+
+```
+设置 → 插件 → Xray 代理    ← 粘贴 / 保存 / 开关
+左侧 2Xray（地球图标）     ← 扫码 / 复制
+```
+
+> 浏览器没有 `BarcodeDetector` 时（部分 Windows Chrome），左侧面板会提示；
+> 可改用插件目录里的 `tools/scanner.html`（内置 jsQR 兜底），再把链接粘回设置页。
+
 ## 配置导入：分享链接 / 二维码
 
 三种入口最终都归约为同一段 `vless://` 文本，所以解析器只有一份（[lib/share-link.js](lib/share-link.js)），UI 只负责把文本拿到手。

package/index.js

@@ -9,6 +9,19 @@ import { installTools } from './lib/tools.js'
 
 export const name = 'dsh-2xray'
 
+/**
+ * Settings schema, exported only when the harness copy of Schemastery is
+ * resolvable (it lives beside the plugin in the profile). Without it the plugin
+ * keeps working from YAML config; the Plugins page simply shows no form.
+ */
+let Config
+try {
+  ;({ Config } = await import('./lib/schema.js'))
+} catch {
+  Config = undefined
+}
+export { Config }
+
 /**
  * Host half of dsh-2xray: it supervises one xray-core child process and
  * points the harness' process-global proxy policy at the local inbound.
@@ -28,6 +41,15 @@ export function apply(ctx, rawConfig) {
 
   for (const warning of warnings) logger.warn(`配置警告：${warning}`)
 
+  // Volatile-only settings writes do not remount the fiber; the value is in the
+  // profile patch and takes effect on the next start or plugin reload.
+  if (typeof ctx.on === 'function') {
+    ctx.on('loader/volatile-update', (paths) => {
+      const changed = Array.isArray(paths) ? paths.join(', ') : String(paths ?? '')
+      logger.info(`设置已保存（${changed}）；重启 DSH 后生效`)
+    })
+  }
+
   let dataDir
   try {
     dataDir = resolveDataDir(config)

package/lib/client.js

@@ -0,0 +1,267 @@
+window.__ModuleLoader__.load({
+  id: '@twinsearth/dsh-2xray',
+  factory: (require) => {
+    const React = require('react')
+    const h = React.createElement
+
+    const PANEL_ID = 'xray'
+    const inject = ['slots', 'locale']
+
+    function GlobeIcon() {
+      return h(
+        'svg',
+        {
+          width: 20,
+          height: 20,
+          viewBox: '0 0 24 24',
+          fill: 'none',
+          stroke: 'currentColor',
+          strokeWidth: 1.7,
+          strokeLinecap: 'round',
+          strokeLinejoin: 'round',
+          'aria-hidden': 'true',
+        },
+        h('circle', { cx: 12, cy: 12, r: 9 }),
+        h('ellipse', { cx: 12, cy: 12, rx: 4, ry: 9 }),
+        h('path', { d: 'M3 12h18M4.5 7.5h15M4.5 16.5h15' }),
+      )
+    }
+
+    const styles = {
+      page: { maxWidth: 760, margin: '0 auto', padding: '28px 20px 48px', color: 'var(--dsh-text, #e2e8f0)' },
+      title: { fontSize: 20, fontWeight: 600, margin: '0 0 4px' },
+      hint: { color: 'var(--dsh-text-secondary, #94a3b8)', fontSize: 13, margin: '0 0 20px' },
+      card: { border: '1px solid var(--dsh-border, #334155)', borderRadius: 12, padding: 16, marginBottom: 16 },
+      h2: { fontSize: 15, margin: '0 0 10px' },
+      textarea: {
+        width: '100%',
+        boxSizing: 'border-box',
+        minHeight: 84,
+        padding: 10,
+        borderRadius: 8,
+        border: '1px solid var(--dsh-border, #334155)',
+        background: 'var(--dsh-surface, #0b1220)',
+        color: 'inherit',
+        font: '13px/1.5 ui-monospace, Consolas, monospace',
+        resize: 'vertical',
+      },
+      row: { display: 'flex', gap: 10, flexWrap: 'wrap', alignItems: 'center', marginTop: 10 },
+      button: {
+        padding: '8px 14px',
+        borderRadius: 8,
+        border: '1px solid var(--dsh-border, #334155)',
+        background: 'var(--dsh-surface-raised, #334155)',
+        color: 'inherit',
+        cursor: 'pointer',
+        fontSize: 14,
+      },
+      primary: { background: '#2563eb', borderColor: '#2563eb', color: '#fff' },
+      status: { fontSize: 13, marginTop: 10, minHeight: 20, color: 'var(--dsh-text-secondary, #94a3b8)' },
+      video: { width: '100%', maxHeight: 320, borderRadius: 8, background: '#000', marginTop: 12, display: 'none' },
+      steps: { margin: '10px 0 0', paddingLeft: 20, fontSize: 13, color: 'var(--dsh-text-secondary, #94a3b8)' },
+    }
+
+    function XrayPage() {
+      const [text, setText] = React.useState('')
+      const [status, setStatus] = React.useState('')
+      const [statusKind, setStatusKind] = React.useState('')
+      const [scanning, setScanning] = React.useState(false)
+      const videoRef = React.useRef(null)
+      const streamRef = React.useRef(null)
+      const timerRef = React.useRef(null)
+      const detectorRef = React.useRef(null)
+
+      const say = (message, kind) => {
+        setStatus(message)
+        setStatusKind(kind || '')
+      }
+
+      const detector = () => {
+        if (detectorRef.current !== null) return detectorRef.current
+        detectorRef.current = 'BarcodeDetector' in window ? new window.BarcodeDetector({ formats: ['qr_code'] }) : false
+        return detectorRef.current
+      }
+
+      const decodeCanvas = async (canvas) => {
+        const det = detector()
+        if (!det) return null
+        const codes = await det.detect(canvas)
+        return codes && codes.length > 0 ? codes[0].rawValue : null
+      }
+
+      const accept = (value) => {
+        const trimmed = String(value || '').trim()
+        if (!trimmed) return false
+        setText(trimmed)
+        say('已识别：' + trimmed.slice(0, 64) + (trimmed.length > 64 ? '…' : ''), 'ok')
+        return true
+      }
+
+      const onFile = async (event) => {
+        const file = event.target.files && event.target.files[0]
+        if (!file) return
+        say('正在解析图片…')
+        try {
+          const bitmap = await createImageBitmap(file)
+          const scale = Math.min(1, 1600 / Math.max(bitmap.width, bitmap.height))
+          const canvas = document.createElement('canvas')
+          canvas.width = Math.max(1, Math.round(bitmap.width * scale))
+          canvas.height = Math.max(1, Math.round(bitmap.height * scale))
+          canvas.getContext('2d').drawImage(bitmap, 0, 0, canvas.width, canvas.height)
+          const value = await decodeCanvas(canvas)
+          if (!value) say('图片里没有识别到二维码；换一张更清晰/更大的图，或使用插件目录里的 tools/scanner.html（带 jsQR 兜底）。', 'error')
+          else accept(value)
+        } catch (error) {
+          say('解析失败：' + error.message, 'error')
+        }
+      }
+
+      const stop = async () => {
+        if (timerRef.current) {
+          clearInterval(timerRef.current)
+          timerRef.current = null
+        }
+        if (streamRef.current) {
+          for (const track of streamRef.current.getTracks()) track.stop()
+          streamRef.current = null
+        }
+        if (videoRef.current) videoRef.current.srcObject = null
+        setScanning(false)
+      }
+
+      const tick = async () => {
+        const video = videoRef.current
+        if (!video || !streamRef.current) return
+        if (video.readyState < 2 || !video.videoWidth) return
+        const canvas = document.createElement('canvas')
+        canvas.width = video.videoWidth
+        canvas.height = video.videoHeight
+        canvas.getContext('2d').drawImage(video, 0, 0)
+        try {
+          const value = await decodeCanvas(canvas)
+          if (value) {
+            accept(value)
+            await stop()
+            say('已识别并停止扫描。', 'ok')
+          }
+        } catch {
+          // a failed frame is normal while the code is out of view
+        }
+      }
+
+      const startScreen = async () => {
+        if (!navigator.mediaDevices || !navigator.mediaDevices.getDisplayMedia) {
+          say('当前浏览器不支持屏幕捕获；请改用「二维码图片」或 tools/scanner.html。', 'error')
+          return
+        }
+        if (!detector()) {
+          say('当前浏览器没有 BarcodeDetector；请使用插件目录里的 tools/scanner.html（内置 jsQR 兜底）。', 'error')
+          return
+        }
+        try {
+          const stream = await navigator.mediaDevices.getDisplayMedia({ video: { frameRate: 10 }, audio: false })
+          streamRef.current = stream
+          setScanning(true)
+          if (videoRef.current) {
+            videoRef.current.srcObject = stream
+            videoRef.current.style.display = 'block'
+            await videoRef.current.play()
+          }
+          stream.getVideoTracks()[0].addEventListener('ended', stop)
+          say('请把二维码放到共享屏幕上，正在识别…')
+          timerRef.current = setInterval(tick, 350)
+        } catch (error) {
+          say('屏幕共享未开始：' + error.message, 'error')
+          setScanning(false)
+        }
+      }
+
+      React.useEffect(() => () => {
+        if (timerRef.current) clearInterval(timerRef.current)
+        if (streamRef.current) for (const track of streamRef.current.getTracks()) track.stop()
+      }, [])
+
+      const copy = async () => {
+        if (!text.trim()) {
+          say('还没有链接可复制。', 'error')
+          return
+        }
+        try {
+          await navigator.clipboard.writeText(text.trim())
+          say('已复制。粘贴到「插件 → Xray 代理 → 分享链接」后保存，并重启 DSH。', 'ok')
+        } catch {
+          say('复制失败，请手动选中文本复制。', 'error')
+        }
+      }
+
+      return h(
+        'div',
+        { style: styles.page },
+        h('h1', { style: styles.title }, '2Xray'),
+        h('p', { style: styles.hint }, '扫描或粘贴 vless 分享链接，然后到「插件 → Xray 代理」里保存。'),
+        h(
+          'section',
+          { style: styles.card },
+          h('h2', { style: styles.h2 }, '1. 二维码图片'),
+          h('input', { type: 'file', accept: 'image/*', onChange: onFile, disabled: scanning }),
+          h('div', { style: styles.status, 'aria-live': 'polite' }, status),
+        ),
+        h(
+          'section',
+          { style: styles.card },
+          h('h2', { style: styles.h2 }, '2. 扫描屏幕二维码'),
+          h(
+            'div',
+            { style: styles.row },
+            h('button', { type: 'button', style: { ...styles.button, ...styles.primary }, onClick: startScreen, disabled: scanning }, scanning ? '扫描中…' : '开始扫描屏幕'),
+            h('button', { type: 'button', style: styles.button, onClick: stop, disabled: !scanning }, '停止'),
+          ),
+          h('video', { ref: videoRef, playsInline: true, muted: true, style: styles.video }),
+        ),
+        h(
+          'section',
+          { style: styles.card },
+          h('h2', { style: styles.h2 }, '3. 分享链接'),
+          h('textarea', {
+            style: styles.textarea,
+            value: text,
+            placeholder: 'vless://uuid@host:443?security=reality&sni=...&pbk=...#备注',
+            onChange: (event) => setText(event.target.value),
+          }),
+          h(
+            'div',
+            { style: styles.row },
+            h('button', { type: 'button', style: { ...styles.button, ...styles.primary }, onClick: copy }, '复制链接'),
+            h('span', { style: { ...styles.status, marginTop: 0, color: statusKind === 'error' ? '#f87171' : statusKind === 'ok' ? '#4ade80' : undefined } }, status),
+          ),
+          h(
+            'ol',
+            { style: styles.steps },
+            h('li', null, '复制上面的 vless:// 链接；'),
+            h('li', null, '打开 设置 → 插件 → Xray 代理，粘贴到「分享链接」并保存；'),
+            h('li', null, '重启 DSH，状态变为 ready 后即生效。'),
+          ),
+        ),
+      )
+    }
+
+    function apply(ctx) {
+      ctx.effect(
+        () =>
+          ctx.slots.inject('main', () =>
+            ctx.slots.register({ name: 'main', key: PANEL_ID }, XrayPage),
+          ),
+        'dsh-2xray: main panel',
+      )
+      ctx.effect(
+        () =>
+          ctx.slots.inject('sidebar.panellist', () =>
+            ctx.slots.register({ name: 'sidebar.panellist', id: PANEL_ID, order: 1, label: () => '2Xray' }, GlobeIcon),
+          ),
+        'dsh-2xray: sidebar entry',
+      )
+    }
+
+    return { apply, inject, PANEL_ID }
+  },
+})

package/lib/config.js

@@ -213,6 +213,22 @@ function validateEndpoint(endpoint, prefix, errors, warnings) {
   }
 }
 
+/**
+ * Schemastery resolves volatile fields to `{ get }` references. Normalization
+ * must see their values, so unwrap them before merging defaults.
+ */
+function unwrapVolatile(value) {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(unwrapVolatile)
+  const keys = Object.keys(value)
+  if (keys.length === 1 && keys[0] === 'get' && typeof value.get === 'function') {
+    return unwrapVolatile(value.get())
+  }
+  const out = {}
+  for (const key of keys) out[key] = unwrapVolatile(value[key])
+  return out
+}
+
 /**
  * Normalize a raw `config:` block from `cordis.patch.yml` into the shape the
  * rest of the plugin consumes.
@@ -221,6 +237,7 @@ function validateEndpoint(endpoint, prefix, errors, warnings) {
  * @returns normalized config plus field-level validation results.
  */
 export function normalizeConfig(raw) {
+  raw = unwrapVolatile(raw)
   const errors = []
   const warnings = []
   const merged = merge(clone(DEFAULT_CONFIG), raw)

package/lib/schema.js

@@ -0,0 +1,85 @@
+/**
+ * Settings schema for the host half.
+ *
+ * Only the fields that should be editable from the Plugins page are declared:
+ * Schemastery preserves unknown keys, so `nodes`, `routing`, `noProxy` and the
+ * rest of the advanced YAML config pass through untouched.
+ *
+ * Every editable field is `volatile`: the settings page only writes volatile
+ * paths, and a volatile-only change does not remount the plugin fiber. The host
+ * logs a "restart required" note; the value lands in the profile patch and is
+ * applied on the next DSH start (or plugin reload).
+ *
+ * Schemastery is a harness package that lives beside the installed plugin; the
+ * bare import works there. The fallback keeps local checkouts and tests working
+ * by resolving the copy from the active profile.
+ */
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+async function loadSchema() {
+  try {
+    return (await import('@deepseek-ai/schemastery')).default
+  } catch {
+    // local checkout / test: borrow the profile's copy
+  }
+  const home = process.env.USERPROFILE ?? process.env.HOME
+  const anchors = home
+    ? [
+        join(home, '.dsh', 'profiles', 'desktop', 'package.json'),
+        join(home, '.dsh', 'profiles', 'web', 'package.json'),
+      ]
+    : []
+  for (const anchor of anchors) {
+    try {
+      const file = createRequire(anchor).resolve('@deepseek-ai/schemastery')
+      const module = await import(pathToFileURL(file).href)
+      return module.default ?? module
+    } catch {
+      // try the next profile
+    }
+  }
+  throw new Error('@deepseek-ai/schemastery is not resolvable')
+}
+
+const Schema = await loadSchema()
+
+export const Config = Schema.object({
+  enabled: Schema.boolean()
+    .default(false)
+    .description('启用 Xray 代理：生成配置、启动子进程并接管全局出口。')
+    .volatile(),
+  shareLink: Schema.string()
+    .default('')
+    .description('vless:// 分享链接（二维码里就是这段文本）。支持 security=reality/tls/none。')
+    .volatile(),
+  binary: Schema.object({
+    path: Schema.string()
+      .default('')
+      .description('xray 可执行文件绝对路径；留空按 插件 bin/ → 数据目录 → PATH 查找。')
+      .volatile(),
+  }),
+  inbound: Schema.object({
+    port: Schema.natural()
+      .default(20808)
+      .description('本地 HTTP 入站端口（DSH 与 web_fetch 都经它出网）。')
+      .volatile(),
+  }),
+  takeover: Schema.string()
+    .default('auto')
+    .description('auto：已有代理时不覆盖；force：强制接管；off：只启动 xray 不接管。')
+    .volatile(),
+  functionalProbe: Schema.object({
+    enabled: Schema.boolean()
+      .default(true)
+      .description('启动后经本地入站请求一次 204，验证链路；离线环境可关闭。')
+      .volatile(),
+  }),
+  control: Schema.object({
+    enabled: Schema.boolean()
+      .default(false)
+      .description('启用 gRPC 控制面（多节点切换与流量统计，需 xray 2024-09+）。')
+      .volatile(),
+  }),
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/dsh-2xray",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "DSH-2Xray: supervises xray-core and routes DSH process-wide HTTP(S) traffic through its local inbound, with optional multi-node gRPC control plane",
   "type": "module",
@@ -10,7 +10,8 @@
     "./package.json": "./package.json",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
+    "./icon": "./icon.svg",
+    "./client": "./lib/client.js"
   },
   "files": [
     "index.js",
@@ -26,7 +27,8 @@
     "docs/*.md",
     "examples/*.json",
     "scripts/*.mjs",
-    "test/*.js"
+    "test/*.js",
+    "tools/*"
   ],
   "scripts": {
     "test": "node --test --test-isolation=none test/*.test.js",
@@ -39,6 +41,12 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
     }
   }
 }

package/test/client.test.js

@@ -0,0 +1,56 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+test('the client bundle registers a main panel and a sidebar entry', async () => {
+  let captured
+  globalThis.window = { __ModuleLoader__: { load(module) { captured = module } } }
+  try {
+    await import('../lib/client.js')
+  } finally {
+    delete globalThis.window
+  }
+
+  assert.equal(captured.id, '@twinsearth/dsh-2xray')
+  const createElement = (type, props, ...children) => ({ type, props, children })
+  const react = {
+    createElement,
+    useState: () => [undefined, () => {}],
+    useEffect: () => {},
+    useRef: () => ({ current: null }),
+  }
+  const mod = captured.factory((name) => {
+    if (name === 'react') return react
+    throw new Error('unexpected module ' + name)
+  })
+
+  assert.equal(typeof mod.apply, 'function')
+  assert.deepEqual(mod.inject, ['slots', 'locale'])
+  assert.equal(mod.PANEL_ID, 'xray')
+
+  const registrations = []
+  const ctx = {
+    effect(fn) {
+      fn()
+    },
+    slots: {
+      inject(_name, callback) {
+        callback()
+      },
+      register(definition, component) {
+        registrations.push({ definition, component })
+      },
+    },
+  }
+  mod.apply(ctx)
+
+  assert.deepEqual(
+    registrations.map((entry) => entry.definition.name),
+    ['main', 'sidebar.panellist'],
+  )
+  assert.equal(registrations[0].definition.key, 'xray')
+  assert.equal(registrations[1].definition.id, 'xray')
+  assert.equal(registrations[1].definition.order, 1)
+  assert.equal(registrations[1].definition.label(), '2Xray')
+  const icon = registrations[1].component()
+  assert.equal(icon.type, 'svg')
+})