@qic-9821/dsh-plugin-sync 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QIC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @qic-9821/dsh-plugin-sync
+
+让两台机器上的 **DeepSeek Harness 插件状态** 保持一致：装了什么、开着还是关着、配置是什么、本地插件目录要不要一起搬过去。
+
+npm：[`@qic-9821/dsh-plugin-sync`](https://www.npmjs.com/package/@qic-9821/dsh-plugin-sync) · 仓库：<https://github.com/QIC-9821/dsh-plugin-sync> · MIT
+
+![独立面板](docs/panel.png)
+
+配套：`设置 → 插件同步`（系统设置菜单栏里的独立一页）、`设置 → 插件 → 同步`（Plugins 段内的一页）、独立面板 `http://127.0.0.1:<端口>/plugin-sync`、两个 Agent 工具 `plugin_sync` / `plugin_sync_config`。
+
+## 安装
+
+两台机器各装一次（要同步的两端都必须装，否则对端接口不存在）：
+
+```bash
+# 已经解出源码时：把目录交给宿主安装（推荐，会自动写 profile 依赖与 lock）
+dsh plugin --profile <profile> add /path/to/dsh-plugin-sync
+
+# 或者从 npm 装
+dsh plugin --profile <profile> add @qic-9821/dsh-plugin-sync
+```
+
+在 App 里也可以走「设置 → 插件 → 安装」给绝对路径。装完刷新一次页面就会多出 `设置 → 插件同步`；宿主进程不用重启（路由和工具会当场挂上）。
+
+安装后两台机器都要做一次：
+
+1. 打开 `设置 → 插件同步`，填对端（地址或 SSH 主机/私钥）和两端相同的令牌。
+2. 改 `direction`（哪边推、哪边收）和要开的权限。
+3. 用「只看计划」确认清单再「立即同步」。
+
+
+## 能同步什么
+
+| 能力 | 开关 | 说明 |
+| --- | --- | --- |
+| 插件清单与启停 | `capPlugins` | 每台机器装了哪些 bundle、每个 loader 条目开着还是关着 |
+| 插件配置 | `capConfig` | `cordis.patch.yml` 里每个 bundle 的 `config:` 段 |
+| 安装 / 升级 / 卸载 | `capInstall` | 通过宿主 `pluginManager` 跑 pnpm、改 `package.json` 与 `node_modules` |
+| 复制插件二进制 | `capFiles` | 把本机 `file:` 插件的源码目录 tar 过去再装（跨机不需要 git/npm 可达） |
+| 允许对端改动本机 | `capRemoteApply` | 关掉后对端连读都读不到 |
+| 同步密钥字段 | `capSecrets` | 默认关；`appSecret` / `token` / `*key*` 一律写成 `[redacted]` |
+
+安装、升级、卸载、启停全部走宿主的 `pluginManager` 服务（`installBundle` / `updateBundle` / `removeBundle` / `setBundleEnabled` / `setPluginEnabled`），不自己拼 pnpm 命令行、不手写 profile 的 `package.json`，失败由宿主回滚它自己的改动。
+
+## 怎么连
+
+两台机器都装本插件，然后在各自设置页填对端：
+
+- **HTTP**：直接填对端 Web 地址（要求对端端口可达）。
+- **SSH 隧道**：填 `主机 / 用户 / 端口 / 私钥 / 对端 Web 端口`。本插件按需 `ssh -N -L` 开一条本地转发，再走同一套 HTTP 协议——跨公网、对端只监听 127.0.0.1 的情况用这个（云端的 qqbot profile 就是）。
+
+两端都要填 **同一个令牌**。令牌只用于 `/plugin-sync/peer/*` 这一组接口；同一台机器上的设置页用同源请求，不需要令牌。
+
+## 同步时机
+
+- `autoStart`：DSH 启动后约 25 秒跑一轮（等宿主把插件挂完）。
+- `autoRestart`：进程重启后再补一轮（约 2 分钟），处理对端还在启动的情况；服务器重启后的同步就是这条。
+- `intervalMinutes`：固定间隔（0 = 关）。
+- 手动：面板/设置页按钮，或工具 `plugin_sync` `action="run"`。
+
+## 冲突策略
+
+- `local`：以发起方为准（默认）
+- `peer`：以接收方为准（不动对端的启停状态）
+- `newest`：版本比较，只升不降
+
+`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app` 和本插件自己永远不参与启停/卸载；`include` / `exclude` 支持精确名字和 `前缀*`。
+
+**宿主自带的包默认不同步。** `@deepseek-ai/*` 下的包是 DSH 自己的组件，两台机器的版本和平台本来就可能不一样（Windows 桌面端 vs Linux 服务器端），推过去只会把对端弄坏。要同步其中某个，就在 `include` 里点名（例如 `include: ["@deepseek-ai/dsh-session-log-*"]`）。
+
+同理，某台机器上「故意关掉」的东西要自己加进 `exclude`：比如桌面端的 `@tencent-connect/dsh-qqbot` 平时是停用的（云端在跑同一个 bot，双开会每条消息回两遍），不排除的话一次 `push` 就会把云端的 QQ 机器人关掉。
+
+## 安全边界
+
+1. 对端接口一律要令牌；没配令牌 = 对端接口全关。
+2. 同步到本机的操作还要再过一遍 `cap*` 权限（对端有权限、本机没开，照样落地不了）。
+3. 写 `cordis.patch.yml` 前自动备份到 `~/.dsh/plugin-sync/backups/`（带时间戳）。
+4. 本机永远只改自己的 profile，不写共享目录；状态文件 `~/.dsh/plugin-sync/state.json` 原子写。
+
+## 状态文件
+
+```
+~/.dsh/plugin-sync/state.json     设置 + 上次运行结果
+~/.dsh/plugin-sync/backups/       cordis.patch.yml 备份
+~/.dsh/plugin-sync/incoming/      从对端收到的插件源码
+```
+
+## 工具
+
+- `plugin_sync` — `status` / `plan` / `run`（可带 `direction`）
+- `plugin_sync_config` — `get` / `set`（`patch` 合并设置；不返回令牌）
+
+## 排查脚本
+
+宿主多半在别的进程里，改完代码不想重启时用这两个脚本验证：
+
+```bash
+node scripts/verify-plan.mjs          # 抓两端快照，用当前 merge.js 打印计划
+node scripts/probe-apply.mjs          # 过隧道打一次 /peer/apply（默认一个不存在的行，验证鉴权与错误回报）
+```
+
+## 已知边界
+
+- 只同步插件层：workspace、会话、密钥凭据（`.credentials.yaml`）不在范围内。
+- `config:` 段的写出是 flow mapping（`config: {"a":1}`），YAML 合法但和原有块状写法不同；无法解析的写法不会被动。
+- 安装 `file:` 插件时，对端会收到一份源码副本（排除 `node_modules` / `.git`），路径是本机的 `incoming/` 目录。
+
+## 开发
+
+```bash
+node --test test/*.test.js     # 25 个用例，纯 Node，无第三方依赖
+node scripts/verify-plan.mjs   # 对真实的两台机器跑一次计划，不落地
+```
+
+设置页在 `client.js` 里注册 `settings.section`（id `plugin-sync`，order 16）与 `settings.plugins.tab`；宿主侧路由在 `lib/http.js`，写操作在 `lib/apply.js`，计划器是纯函数 `lib/merge.js`（好单测）。
+
+设置页在云端实例里的样子：
+
+![设置页](docs/settings-sync.png)
+
+## 许可
+
+MIT © 2026 QIC-9821
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/client.js

@@ -0,0 +1,354 @@
+window.__ModuleLoader__.load({
+  id: '@qic-9821/dsh-plugin-sync',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+    const { useCallback, useEffect, useMemo, useState } = React
+
+    const API = '/plugin-sync/api/'
+
+    const CARD = {
+      border: '1px solid var(--dsh-border, rgba(127,127,127,.28))',
+      borderRadius: 12,
+      padding: '14px 16px',
+      marginBottom: 14,
+      background: 'var(--dsh-surface, transparent)',
+    }
+    const LABEL = { fontSize: 12.5, opacity: 0.7, marginBottom: 4 }
+    const INPUT = {
+      width: '100%',
+      boxSizing: 'border-box',
+      padding: '6px 9px',
+      borderRadius: 8,
+      border: '1px solid var(--dsh-border, rgba(127,127,127,.35))',
+      background: 'transparent',
+      color: 'inherit',
+      font: 'inherit',
+    }
+    const BUTTON = {
+      padding: '7px 14px',
+      borderRadius: 8,
+      border: '1px solid var(--dsh-border, rgba(127,127,127,.35))',
+      background: 'transparent',
+      color: 'inherit',
+      cursor: 'pointer',
+      font: 'inherit',
+    }
+    const BUTTON_PRIMARY = { ...BUTTON, background: 'var(--dsh-accent, #3b82f6)', borderColor: 'var(--dsh-accent, #3b82f6)', color: '#fff' }
+    const ROW = { display: 'flex', justifyContent: 'space-between', gap: 12, padding: '4px 0', fontSize: 13 }
+    const MUTED = { fontSize: 12.5, opacity: 0.65 }
+
+    async function api(path, options) {
+      const response = await fetch(API + path, options)
+      const text = await response.text()
+      try {
+        return JSON.parse(text)
+      } catch {
+        return { error: text || `HTTP ${response.status}` }
+      }
+    }
+
+    function post(path, body) {
+      return api(path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body ?? {}),
+      })
+    }
+
+    function Card(props) {
+      return h('div', { style: CARD }, [
+        h('div', { key: 'title', style: { fontSize: 13.5, fontWeight: 600, marginBottom: 10 } }, props.title),
+        props.children,
+      ])
+    }
+
+    function Field(props) {
+      return h('div', { style: { marginTop: 10 } }, [
+        props.label ? h('div', { key: 'label', style: LABEL }, props.label) : null,
+        props.children,
+      ])
+    }
+
+    function Toggle(props) {
+      return h(
+        'label',
+        {
+          key: props.id,
+          style: {
+            display: 'flex',
+            gap: 10,
+            alignItems: 'flex-start',
+            padding: '6px 0',
+            borderBottom: '1px dashed var(--dsh-border, rgba(127,127,127,.25))',
+            cursor: 'pointer',
+          },
+        },
+        [
+          h('input', {
+            key: 'box',
+            type: 'checkbox',
+            checked: Boolean(props.checked),
+            onChange: (event) => props.onChange(event.target.checked),
+            style: { marginTop: 2 },
+          }),
+          h('span', { key: 'text' }, [
+            h('b', { key: 'name' }, props.label),
+            props.desc ? h('div', { key: 'desc', style: MUTED }, props.desc) : null,
+          ]),
+        ],
+      )
+    }
+
+    function SyncSettings(props) {
+      const [state, setState] = useState(null)
+      const [error, setError] = useState(null)
+      const [busy, setBusy] = useState(null)
+      const [out, setOut] = useState('')
+      const [draft, setDraft] = useState({})
+
+      const load = useCallback(async () => {
+        try {
+          const next = await api('state')
+          if (next && next.error) setError(String(next.error))
+          else {
+            setState(next)
+            setError(null)
+          }
+        } catch (cause) {
+          setError(cause?.message || String(cause))
+        }
+      }, [])
+
+      useEffect(() => {
+        void load()
+      }, [load])
+
+      const config = state?.config || {}
+      const value = useCallback((key) => (draft[key] !== undefined ? draft[key] : config[key]), [draft, config])
+      const setValue = useCallback((key, next) => setDraft((current) => ({ ...current, [key]: next })), [])
+
+      const save = useCallback(async () => {
+        if (Object.keys(draft).length === 0) return
+        setBusy('save')
+        try {
+          const next = await post('config', { ...draft, capabilities: collectCaps(draft) })
+          if (next && next.status) {
+            setState(next)
+            setDraft({})
+          }
+          setError(next?.error ? String(next.error) : null)
+        } catch (cause) {
+          setError(cause?.message || String(cause))
+        } finally {
+          setBusy(null)
+        }
+      }, [draft])
+
+      // capability toggles land in draft under their own keys
+      const collectCaps = (patch) => {
+        const caps = {}
+        for (const cap of state?.capabilityCatalog || []) {
+          if (patch[cap.key] !== undefined) caps[cap.key] = patch[cap.key]
+        }
+        return caps
+      }
+
+      const run = useCallback(
+        async (action) => {
+          setBusy(action)
+          setOut(action === 'sync' ? '同步中…' : '计算中…')
+          try {
+            const result = action === 'sync' ? await post('sync', {}) : await api('plan')
+            setOut(JSON.stringify(result, null, 2).slice(0, 20000))
+            if (result?.status) setState((current) => (current ? { ...current, status: result.status } : current))
+          } catch (cause) {
+            setOut(String(cause?.message || cause))
+          } finally {
+            setBusy(null)
+          }
+        },
+        [],
+      )
+
+      const status = state?.status
+      const statusRows = useMemo(() => {
+        if (!status) return []
+        return [
+          [
+            '本机',
+            status.local
+              ? `${status.local.node || '?'} · ${status.local.profile || '?'} · ${status.local.bundles} 包 / ${status.local.plugins} 条目`
+              : status.localError || '读取失败',
+          ],
+          ['profile 目录', status.profileDir || '?'],
+          ['版本', status.package ? `${status.package.name} ${status.package.version || ''}`.trim() : '?'],
+          ['对端', status.peer?.describe || '?'],
+          [
+            '上次同步',
+            status.lastRun
+              ? `${formatTime(status.lastRun.at)} · ${status.lastRun.ok ? '成功' : `失败：${status.lastRun.error || ''}`}`
+              : '还没跑过',
+          ],
+          ['当前', status.running ? '同步中…' : '空闲'],
+        ]
+      }, [status])
+
+      if (!state) {
+        return h('div', { style: { padding: 16, fontSize: 13 } }, error ? `读取失败：${error}` : '读取中…')
+      }
+
+      return h(
+        'div',
+        { style: { padding: props.compact ? 0 : '4px 2px 24px' } },
+        [
+          error
+            ? h('div', { key: 'err', style: { color: 'var(--dsh-danger, #d9534f)', marginBottom: 10, fontSize: 13 } }, error)
+            : null,
+
+          h(Card, { key: 'status', title: '状态' }, [
+            ...statusRows.map(([key, text], index) =>
+              h('div', { key: `row-${index}`, style: ROW }, [
+                h('span', { key: 'k', style: { opacity: 0.65 } }, key),
+                h('span', { key: 'v', style: { textAlign: 'right', wordBreak: 'break-all' } }, String(text)),
+              ]),
+            ),
+            h('div', { key: 'actions', style: { display: 'flex', gap: 8, marginTop: 12, flexWrap: 'wrap' } }, [
+              h(
+                'button',
+                { key: 'sync', style: BUTTON_PRIMARY, disabled: Boolean(busy), onClick: () => run('sync') },
+                busy === 'sync' ? '同步中…' : '立即同步',
+              ),
+              h('button', { key: 'plan', style: BUTTON, disabled: Boolean(busy), onClick: () => run('plan') }, '只看计划'),
+              h('button', { key: 'reload', style: BUTTON, disabled: Boolean(busy), onClick: () => void load() }, '刷新'),
+            ]),
+          ]),
+
+          h(Card, { key: 'peer', title: '对端' }, [
+            h(Field, { key: 'mode', label: '连接方式' }, select(value('peerMode'), [
+              ['off', '未配置'],
+              ['http', 'HTTP（对端 Web 端口）'],
+              ['ssh', 'SSH 隧道（推荐，跨公网）'],
+            ], (next) => setValue('peerMode', next))),
+            h(Field, { key: 'url', label: 'HTTP 地址' }, input(value('peerUrl'), 'http://127.0.0.1:18777', (next) => setValue('peerUrl', next))),
+            h('div', { key: 'ssh', style: { display: 'grid', gridTemplateColumns: '2fr 1fr 90px', gap: 8 } }, [
+              h(Field, { key: 'host', label: 'SSH 主机' }, input(value('peerHost'), '114.55.146.70', (next) => setValue('peerHost', next))),
+              h(Field, { key: 'user', label: '用户' }, input(value('peerUser'), 'dsh', (next) => setValue('peerUser', next))),
+              h(Field, { key: 'port', label: '端口' }, input(value('peerPort'), '22', (next) => setValue('peerPort', Number(next) || 22))),
+            ]),
+            h('div', { key: 'tunnel', style: { display: 'grid', gridTemplateColumns: '110px 1fr', gap: 8 } }, [
+              h(Field, { key: 'httpPort', label: '对端 Web 端口' }, input(value('peerHttpPort'), '18777', (next) => setValue('peerHttpPort', Number(next) || 18777))),
+              h(Field, { key: 'key', label: 'SSH 私钥' }, input(value('peerKey'), 'C:\\Users\\QIC\\.ssh\\dsh_cloud_ed25519', (next) => setValue('peerKey', next))),
+            ]),
+            h(Field, { key: 'name', label: '对端名称（显示用）' }, input(value('peerName'), 'cloud', (next) => setValue('peerName', next))),
+            h(
+              Field,
+              { key: 'token', label: config.peerTokenSet ? '对端令牌（留空表示不改）' : '对端令牌（两端要一致）' },
+              input(draft.peerToken ?? '', '两端填同一串随机字符', (next) => setValue('peerToken', next)),
+            ),
+            h('div', { key: 'hint', style: { ...MUTED, marginTop: 8 } }, '两台机器都要装本插件；令牌是「对端」接口的凭据，不填则对端接口一律拒绝。'),
+          ]),
+
+          h(Card, { key: 'direction', title: '同步方式与时機' }, [
+            h(Field, { key: 'dir', label: '方向' }, select(value('direction'), (state.directionCatalog || []).map((item) => [item.key, item.label]), (next) => setValue('direction', next))),
+            h(Field, { key: 'conflict', label: '冲突策略' }, select(value('conflict'), [
+              ['local', '以发起方为准'],
+              ['peer', '以接收方为准'],
+              ['newest', '版本新者优先'],
+            ], (next) => setValue('conflict', next))),
+            h('div', { key: 'sched', style: { marginTop: 10 } }, [
+              h(Toggle, {
+                key: 'enable',
+                label: '总开关',
+                desc: '关掉后「启动时同步」和手动同步都不动作',
+                checked: Boolean(value('enabled')),
+                onChange: (next) => setValue('enabled', next),
+              }),
+              h(Toggle, {
+                key: 'startup',
+                label: '软件启动时同步',
+                desc: 'DSH 启动后约 25 秒跑一轮（等宿主把插件都挂上）',
+                checked: Boolean(value('autoStart')),
+                onChange: (next) => setValue('autoStart', next),
+              }),
+              h(Toggle, {
+                key: 'restart',
+                label: '服务器重启后同步',
+                desc: '进程重启之后再补一轮，处理对端还在启动的情况',
+                checked: Boolean(value('autoRestart')),
+                onChange: (next) => setValue('autoRestart', next),
+              }),
+              h(Field, { key: 'interval', label: '每隔多少分钟同步（0 = 不按间隔）' },
+                input(value('intervalMinutes'), '0', (next) => setValue('intervalMinutes', Number(next) || 0))),
+              h(Field, { key: 'delay', label: '启动后延迟秒数' },
+                input(value('startupDelaySec'), '25', (next) => setValue('startupDelaySec', Number(next) || 0))),
+            ]),
+          ]),
+
+          h(Card, { key: 'caps', title: '权限（每一项可以单独关）' },
+            (state.capabilityCatalog || []).map((cap) =>
+              h(Toggle, {
+                key: cap.key,
+                label: cap.label,
+                desc: cap.desc,
+                checked: Boolean(value(cap.key)),
+                onChange: (next) => setValue(cap.key, next),
+              }),
+            ),
+          ),
+
+          h('div', { key: 'save', style: { display: 'flex', gap: 8, alignItems: 'center' } }, [
+            h('button', { key: 'save', style: BUTTON_PRIMARY, disabled: Boolean(busy) || Object.keys(draft).length === 0, onClick: () => void save() }, '保存设置'),
+            h('span', { key: 'hint', style: MUTED }, Object.keys(draft).length === 0 ? '没有未保存的改动' : `${Object.keys(draft).length} 项待保存`),
+          ]),
+
+          out ? h('pre', { key: 'out', style: { marginTop: 12, whiteSpace: 'pre-wrap', fontSize: 11.5, maxHeight: 260, overflow: 'auto', background: 'rgba(127,127,127,.1)', padding: 10, borderRadius: 8 } }, out) : null,
+        ].filter(Boolean),
+      )
+    }
+
+    function input(current, placeholder, onChange) {
+      return h('input', {
+        style: INPUT,
+        value: current === undefined || current === null ? '' : String(current),
+        placeholder,
+        onChange: (event) => onChange(event.target.value),
+      })
+    }
+
+    function select(current, options, onChange) {
+      return h(
+        'select',
+        { style: INPUT, value: current ?? '', onChange: (event) => onChange(event.target.value) },
+        options.map(([key, label]) => h('option', { key, value: key }, label)),
+      )
+    }
+
+    function formatTime(value) {
+      if (!value) return '?'
+      try {
+        return new Date(value).toLocaleString()
+      } catch {
+        return String(value)
+      }
+    }
+
+    return {
+      inject: ['slots'],
+      apply(ctx) {
+        ctx.slots.inject('settings.section', () =>
+          ctx.slots.register(
+            { name: 'settings.section', id: 'plugin-sync', order: 16, label: () => '插件同步' },
+            SyncSettings,
+          ),
+        )
+        ctx.slots.inject('settings.plugins.tab', () =>
+          ctx.slots.register(
+            { name: 'settings.plugins.tab', id: 'plugin-sync', order: 60, label: () => '同步' },
+            (props) => h(SyncSettings, { ...props, compact: true }),
+          ),
+        )
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-plugin-sync — the row itself. Its settings (peer, capabilities, schedule)
+# are edited from 设置 → 插件同步 and stored in ~/.dsh/plugin-sync/state.json,
+# so this patch stays stable across upgrades.
+- insert:
+    - id: plugin-sync
+      name: '@qic-9821/dsh-plugin-sync'