ygc-dsh-plugin-autoupdate 0.2.1 → 0.5.0

package/README.md

@@ -98,6 +98,129 @@
 | POST | `/restore` | 用某份备份回滚清单 |
 | GET | `/diagnose` | 看插件识别结果（排查「为什么某个包没被检查」） |
 
+## 插件共享（特征文件夹）
+
+把「我这台机器装了什么插件」沉淀成一份可以给别人看的东西，互相补全。
+
+### 目录结构
+
+`插件库` 是**共享文件夹**，一个人一格，自己的所有东西都锁在自己那一格里。
+
+```
+D:\Ai工作空间\插件库\          ← 共享文件夹，两台机器都能读写
+├─ <本机标识>\                  ← 我的格子，例 DSH-7e6b1bb7e052
+│  ├─ PLUGINS.json             我的插件清单（含副本指纹表）
+│  ├─ FEATURE.json             我的身份说明
+│  ├─ OTHERS-PLUGINS.json      我的汇总（本机自用）
+│  ├─ OTHERS-PLUGINS.md        同一份的人读版
+│  └─ local\                  本地 / Git 来源插件的 .tgz 副本
+└─ <别人的标识>\               ← 别人写，我只读
+   ├─ PLUGINS.json
+   ├─ FEATURE.json
+   └─ local\
+```
+
+**没有公共分区。** 早先版本在插件库下分出「特征 / 汇集」两级子目录，那是错的：
+插件库是多人共享的盘，公共目录等于公共广场，所有人的东西往一处堆，谁的产出分不清，
+而且「汇集」会成为多方争写的热点。现在改成：
+
+| 原位置 | 现位置 |
+|---|---|
+| `插件库\特征\<标识>\` | `插件库\<标识>\` |
+| `插件库\汇集\OTHERS-PLUGINS.*` | `插件库\<标识>\OTHERS-PLUGINS.*` |
+
+**汇集只给本机自己用。** 每台机器各自扫一遍插件库下所有人的格子，在自己的格子里
+生成自己的汇总——不做全局总表，因为那需要所有机器写同一个文件，必然是冲突源。
+
+### 本机标识与会话同步插件共用
+
+特征文件夹的目录名就是**本机标识**，格式 `<名称>-<特征值>`，例如 `DSH-7e6b1bb7e052`。
+这套规则和会话同步插件（`ygc-dsh-sync-backup`）**逐字一致**，并且共用同一份身份：
+
+| 项 | 规则 |
+|---|---|
+| 身份来源 | 优先读 `~/.dsh/storages/sync-backup.json` 的 `machineHash` |
+| 特征值 | 6 字节随机数 → 12 位十六进制，**第一次确定后永久固定，永不重算** |
+| 名称部分 | 面板可改；改名只换目录名，特征值不变，旧目录不删 |
+| 落盘位置 | 固定进 `~/.dsh/storages/plugin-autoupdate.json` 的 `shareMachineHash` |
+| 迁移 | 唯一来源是既有 state 里已有的哈希；没有旧值才新生成 |
+
+**为什么必须共用**：两台机器之间的身份只能有一个。会话同步已经把这一格写成了
+`machineId`，插件共享如果自己再算一份（比如主机名-用户名），同一台机器会在共享盘上
+留下两个身份，别人汇总时看到两个「我」，本机自己也不确定该往哪格写。
+
+名称里的非法字符按会话同步的 `joinId` 规则换成下划线；`特征/` 下只写自己那一格，
+写别人的目录会被守卫拒绝（`WRITE_DENIED`）。想强行重算特征值，用
+`POST /settings { shareResetHash: true }`——这是唯一的重算入口，其它情况一律沿用旧值。
+
+
+### 清单里写什么
+
+| 插件来源 | 清单里写什么 | 要不要打副本 |
+|---|---|---|
+| `registry`（能联网更新） | 名称 + 版本 | **不打**，对方自己从 registry 拉 |
+| `local`（`file:` 本地路径） | 名称 + 版本 + 来源说明 | **打**，`local/<name>-<version>.tgz` |
+| `git`（GitHub 等） | 名称 + 版本 | **打**，同上 |
+| `installation`（随 DSH 安装提供） | **不写** | 别人本来就有，也没版本号可装 |
+
+副本是 npm 标准 tgz（`package/` 前缀），排除 `node_modules`、`.git`、`__pycache__`、`*.bak-*`。
+单包上限 96 MB，单个特征的副本总量上限 512 MB，同名插件只留最近 2 个版本。
+`link:` 装的包在 `node_modules` 下是符号链接，打包时按 `realpath` 追到真实目录。
+
+### 什么时候跑
+
+**每次巡检跑一次**——巡检 = 自动更新的那一轮定时检查（间隔见「检查频率」）。
+顺序是先查更新、再同步共享；更新失败不影响共享同步。面板上也有「立即同步一次」。
+
+每次同步都幂等：
+
+- 清单内容（除 `generatedAt` / `lastSyncAt` 这类时间字段）没变 → 不重写文件
+- 源目录指纹（文件数 + 最大 mtime + 总字节）没变 → 不重压 `.tgz`，直接复用
+- 本机标识第一次同步时固定进 state，之后每轮原样传回，不做任何重算
+
+所以几百 MB 的本地插件不会把每轮巡检拖慢。
+
+### 拉别人的清单
+
+把别人的 `<别人的标识>\` 整个目录直接放进 `插件库\`（同步盘自动同步也行），然后：
+
+1. 面板点「重新读取」，或等下一次巡检；
+2. 自己格子里的 `OTHERS-PLUGINS.json` 生成合并后的总清单；
+3. 面板「他人插件（本机没有的）」里逐个点「安装」。
+
+**不自动安装。** 别人的插件清单可能包含你不想要的东西，装机这个动作必须人工点。
+
+合并去重规则：
+
+- 去重键是包名；多本特征都有同一插件时，版本取**更高**的那份（按语义版本比，不看文件时间）
+- 副本跟着最高版本走；`features` 里记下它出现在哪几本
+- 「本机有没有」按 profile 的 `dsh.profile.bundles` 判断，不看 `node_modules`（那里塞满传递依赖）
+- 没 `PLUGINS.json` 的目录只记一条提示，不报错
+
+### 装的时候走哪条路
+
+| 对方特征里有 | 用的 spec |
+|---|---|
+| `.tgz` 副本 | `file:<对方副本的绝对路径>`（正斜杠） |
+| 只有名称（registry 来源） | `<name>@<version>` |
+| 既没副本又不是 registry | 拒绝，说明原因 |
+
+装完自动把包名补进 profile 的 `dsh.profile.bundles`——不补的话插件装下来但不会加载。
+装之前同样会快照 profile 三个清单文件，出问题用 `/restore` 回滚。**装完必须完全退出 DSH 再重开。**
+
+### 共享相关接口
+
+| 方法 | 路径 | 作用 |
+|---|---|---|
+| GET | `/share` | 我的特征现状 + 他人清单（含每项是否已装、有没有副本） |
+| POST | `/share/sync` | 立即同步一次（我的清单 + 副本 + 他人汇集） |
+| POST | `/share/install` | 安装他人清单里的一个插件（body: `{ name }`） |
+
+设置项（走 `/settings`）：`shareEnabled`、`shareLibraryRoot`、`shareFeatureName`、`shareResetHash`。
+
+`shareFeatureName` 只改**名称部分**，特征值不动；`shareResetHash: true` 是唯一的重算入口，
+会让下次同步重新解析特征值（正常情况别用，会让目录漂移、别人看到两个你）。
+
 ## 自检
 
 ```powershell
@@ -105,13 +228,15 @@ $node = "C:\DeepSeekHarness\resources\runtime\primary-runtime\dependencies\node\
 & $node "C:\DSH-Work\plugin-autoupdate\pkg\test\all.mjs"
 ```
 
-四个套件：
+八个套件：
 
 | 套件 | 覆盖 |
 |---|---|
 | `selftest.mjs` | 版本比较（含 prerelease）、状态规范化夹紧、延迟判定、registry packument 解析、本机 profile 识别 |
 | `workspace-merge.test.mjs` | `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 合并（同名并成一行、不重复、CRLF 保持、段落连续） |
 | `api-smoke.test.mjs` | 用假 ctx 真加载 Host 半，走完全部 API 路由；状态写在临时 HOME，不碰真实 profile |
+| `machine.test.mjs` | 本机标识：继承会话同步的 machineId、固定后不漂移、改名不换特征值、卸载会话同步后旧值仍有效、写边界（别人的格 / `../` 逃逸 / 前缀相近） |
+| `share.test.mjs` | 特征文件夹：清单分类（registry 只写名 / 本地打副本 / 宿主自带不写）、tgz 结构、同步幂等与副本复用、他人清单合并去重、安装路径选择、特征名防上跳 |
 | `client-smoke.test.mjs` | 在 Node 里用假 `document` / React 求值 `client.js`，验证插槽注册、locale 注册、面板首渲染 |
 
 ## 边界
@@ -120,6 +245,9 @@ $node = "C:\DeepSeekHarness\resources\runtime\primary-runtime\dependencies\node\
 - 只在 `registry` 来源上工作；`local` / `git` / `installation` 来源只显示、不处理
 - 更新失败只记历史，不自动回滚（避免把用户自己手改的清单吞掉）；要回滚用 `/restore`
 - DSH 关闭期间不检查（进程内定时器的固有限制）；重开后会立刻按上游发布时间重新判定
+- 共享只**同步清单与副本**，不自动安装别人的插件；安装必须人工点选
+- 只写 `插件库\<本机标识>\` 那一格，别人的格子只读（写入口有守卫）
+- 不在插件库根下留任何公共文件或公共目录
 
 ## 踩过的坑
 

package/client.js

@@ -44,6 +44,13 @@ const CSS = `
 .pau-switch{display:inline-flex;align-items:center;gap:8px;font-size:13px;cursor:pointer;user-select:none}
 .pau-switch input{width:16px;height:16px;cursor:pointer}
 .pau-actions{display:flex;gap:10px;flex-wrap:wrap;align-items:center}
+.pau-share-path{font-family:ui-monospace,Menlo,Consolas,monospace;font-size:12px;word-break:break-all;color:var(--dsw-alias-label-secondary,#555)}
+.pau-tag-mine{background:var(--dsw-alias-info-tint,#e0f2fe);color:var(--dsw-alias-info,#0369a1)}
+.pau-grid{display:flex;flex-direction:column;gap:8px}
+.pau-other{display:flex;align-items:center;gap:10px;padding:8px 0;border-bottom:1px solid var(--dsw-alias-border-l25,#f0f0f0);flex-wrap:wrap}
+.pau-other:last-child{border-bottom:none}
+.pau-other-main{flex:1;min-width:200px}
+.pau-scroll{max-height:420px;overflow:auto}
 `;
 
 const API = '/api/local/plugin-autoupdate';
@@ -87,6 +94,7 @@ function makePanel(React) {
 
   return function AutoUpdatePanel() {
     const [snap, setSnap] = useState(null);
+    const [shareDetail, setShareDetail] = useState(null);
     const [busy, setBusy] = useState('');
     const [error, setError] = useState('');
     const [note, setNote] = useState('');
@@ -95,6 +103,18 @@ function makePanel(React) {
     const apply = useCallback((next) => {
       if (!next) return;
       setSnap(next);
+      // 共享面板的明细单独取一次：它是扫盘结果，比状态文件重，不跟 15 秒轮询一起刷
+      if (next.share && next.share.detail) setShareDetail(next.share.detail);
+    }, []);
+
+    const loadShareDetail = useCallback(async () => {
+      try {
+        const data = await call('/share');
+        if (data && data.share && data.share.detail) setShareDetail(data.share.detail);
+        if (data) setSnap(data);
+      } catch (err) {
+        setError(String(err.message || err));
+      }
     }, []);
 
     const refresh = useCallback(async () => {
@@ -115,6 +135,11 @@ function makePanel(React) {
       };
     }, [refresh]);
 
+    useEffect(() => {
+      // 共享明细只取一次，之后靠「立即同步」/ 安装后刷新
+      loadShareDetail();
+    }, [loadShareDetail]);
+
     const run = async (name, fn) => {
       setBusy(name);
       setError('');
@@ -511,6 +536,238 @@ function makePanel(React) {
       ),
     );
 
+    const share = snap.share || {};
+    const detail = shareDetail || null;
+    const myFeature = (detail && detail.myFeature) || share.effectiveFeature || '';
+    const libRoot = (detail && detail.libraryRoot) || share.effectiveRoot || '';
+    const others = (detail && Array.isArray(detail.others) ? detail.others : []).filter((p) => !p.installed);
+    const installedFromOthers = (detail && Array.isArray(detail.others) ? detail.others : []).filter(
+      (p) => p.installed,
+    );
+    const sources = (detail && Array.isArray(detail.sources) ? detail.sources : []) || [];
+
+    const shareCard = h(
+      'div',
+      { className: 'pau-card' },
+      h(
+        'div',
+        { className: 'pau-card-h' },
+        h('h3', { className: 'pau-card-t' }, '插件共享（特征文件夹）'),
+        h(
+          'span',
+          { className: share.enabled ? 'pau-tag pau-tag-ok' : 'pau-tag' },
+          share.enabled ? '每次巡检自动同步' : '自动同步已关闭',
+        ),
+      ),
+      h(
+        'p',
+        { className: 'pau-sub' },
+        '插件库是共享文件夹，一个人一格：我的清单、本地插件副本、我自己的汇总全都写在「插件库\\<我的特征>」这一格里面。能联网更新的插件只写名称，本地/Git 来源的打成 .tgz 副本一起放过去。别人的格子只读，汇总也是各机扫一遍自己算，不放在公共位置。',
+      ),
+      h(
+        'label',
+        { className: 'pau-switch' },
+        h('input', {
+          type: 'checkbox',
+          checked: !!share.enabled,
+          onChange: (e) => patchSettings({ shareEnabled: e.target.checked }),
+        }),
+        '每次巡检顺带同步一次特征文件夹',
+      ),
+      h(
+        'div',
+        { className: 'pau-field' },
+        h('span', { className: 'pau-field-l' }, '插件库根目录'),
+        h('input', {
+          className: 'pau-input',
+          style: { minWidth: 320, flex: 1 },
+          placeholder: '留空用默认 D:\\Ai工作空间\\插件库',
+          defaultValue: share.libraryRoot || '',
+          onBlur: (e) => patchSettings({ shareLibraryRoot: e.target.value.trim() }),
+        }),
+      ),
+      h(
+        'div',
+        { className: 'pau-field' },
+        h('span', { className: 'pau-field-l' }, '我的特征文件夹名'),
+        h('input', {
+          className: 'pau-input',
+          style: { minWidth: 220 },
+          placeholder: '名称部分，留空用电脑名',
+          defaultValue: share.featureName || '',
+          onBlur: (e) => patchSettings({ shareFeatureName: e.target.value.trim() }),
+        }),
+        h(
+          'span',
+          { className: 'pau-row-d' },
+          share.machineHash ? `特征值 ${share.machineHash}（已固定，改名字不会变）` : '特征值首次同步时固定',
+        ),
+      ),
+      (detail && detail.identity && detail.identity.sharesWithSyncBackup) !== false
+        ? h(
+            'div',
+            { className: 'pau-row-d' },
+            '与会话同步插件共用同一个本机标识，两台机器之间只有「一个我」。',
+          )
+        : h(
+            'div',
+            { className: 'pau-row-d' },
+            '注意：没读到会话同步插件的标识，本插件用了自己的特征值。',
+          ),
+      h('div', { className: 'pau-row-d' }, `我的特征目录：`),
+      h('div', { className: 'pau-share-path' }, `${libRoot}${myFeature ? `\\${myFeature}` : ''}`),
+      h(
+        'div',
+        { className: 'pau-row-d' },
+        `我的汇总（只给本机看，各机自己汇集）：${myFeature ? `\\${myFeature}\\OTHERS-PLUGINS.json` : ''}`,
+      ),
+      h(
+        'div',
+        { className: 'pau-row-d', style: { marginTop: 6 } },
+        `上次同步：${fmtAgo(share.lastSyncAt)}${
+          share.lastResult
+            ? ` · 本机 ${share.lastResult.total} 个插件（副本 ${share.lastResult.bundled}，${share.lastResult.totalMb} MB） · 他人 ${share.lastResult.others} 个，可装 ${share.lastResult.installable}`
+            : ''
+        }`,
+      ),
+      share.lastError
+        ? h('div', { className: 'pau-banner pau-banner-warn', style: { marginTop: 8 } }, `上次同步失败：${share.lastError}`)
+        : null,
+      h(
+        'div',
+        { className: 'pau-actions', style: { marginTop: 12 } },
+        h(
+          'button',
+          {
+            className: 'pau-btn pau-btn-primary',
+            disabled: !!busy,
+            onClick: () =>
+              run('share-sync', async () => {
+                const next = await call('/share/sync', {});
+                const result = next.result || {};
+                if (result && result.ok === false) {
+                  setNote(`同步失败：${result.error || '未知错误'}`);
+                } else {
+                  const counts = (result.mine && result.mine.counts) || {};
+                  const others2 = (result.aggregate && result.aggregate.counts) || {};
+                  setNote(
+                    `同步完成：本机 ${counts.total || 0} 个插件（副本 ${counts.bundled || 0}），他人 ${others2.othersTotal || 0} 个，可装 ${others2.installable || 0} 个`,
+                  );
+                }
+                if (next.share && next.share.detail) setShareDetail(next.share.detail);
+                return next;
+              }),
+          },
+          busy === 'share-sync' ? '同步中…' : '立即同步一次',
+        ),
+        h(
+          'button',
+          {
+            className: 'pau-btn',
+            disabled: !!busy,
+            onClick: () => run('share-reload', async () => {
+              await loadShareDetail();
+              setNote('已重新读取特征文件夹');
+              return null;
+            }),
+          },
+          '重新读取',
+        ),
+      ),
+      h(
+        'div',
+        { className: 'pau-card-h', style: { marginTop: 18, marginBottom: 6 } },
+        h('h4', { className: 'pau-card-t' }, `他人插件（本机没有的 ${others.length} 个）`),
+        h(
+          'span',
+          { className: 'pau-row-d' },
+          sources.length ? `${sources.filter((s) => !s.mine).length} 本外部特征` : '还没有拉到别人的特征',
+        ),
+      ),
+      others.length
+        ? h(
+            'div',
+            { className: 'pau-scroll' },
+            others.map((plugin) =>
+              h(
+                'div',
+                { className: 'pau-other', key: plugin.name },
+                h(
+                  'div',
+                  { className: 'pau-other-main' },
+                  h(
+                    'div',
+                    { className: 'pau-row-t' },
+                    h('span', { className: 'pau-mono' }, plugin.name),
+                    plugin.version ? h('span', { className: 'pau-tag' }, `v${plugin.version}`) : null,
+                    h(
+                      'span',
+                      {
+                        className:
+                          plugin.bundle || plugin.kind === 'registry'
+                            ? 'pau-tag pau-tag-ok'
+                            : 'pau-tag pau-tag-warn',
+                      },
+                      plugin.bundle
+                        ? '含副本，可离线装'
+                        : plugin.kind === 'registry'
+                          ? '需联网拉取'
+                          : '无副本，装不了',
+                    ),
+                    h('span', { className: 'pau-tag pau-tag-mine' }, plugin.features.join(' / ')),
+                  ),
+                  plugin.description
+                    ? h('div', { className: 'pau-row-d' }, plugin.description.slice(0, 140))
+                    : null,
+                ),
+                h(
+                  'button',
+                  {
+                    className: 'pau-btn pau-btn-sm pau-btn-primary',
+                    disabled: !!busy || (!plugin.bundle && plugin.kind !== 'registry'),
+                    title: plugin.bundle ? `安装对方特征里的副本` : '从 registry 安装该版本',
+                    onClick: () =>
+                      run(`share-install:${plugin.name}`, async () => {
+                        const next = await call('/share/install', { name: plugin.name });
+                        setNote((next.result && next.result.message) || `${plugin.name} 已安装`);
+                        if (next.share && next.share.detail) setShareDetail(next.share.detail);
+                        return next;
+                      }),
+                  },
+                  busy === `share-install:${plugin.name}` ? '安装中…' : '安装',
+                ),
+              ),
+            ),
+          )
+        : h(
+            'div',
+            { className: 'pau-empty' },
+            sources.length ? '他人清单里的插件本机都有了' : '把别人的特征文件夹直接放进 插件库\\ 后点「重新读取」',
+          ),
+      installedFromOthers.length
+        ? h(
+            'div',
+            { className: 'pau-row-d', style: { marginTop: 10 } },
+            `已从共享装上 ${installedFromOthers.length} 个：${installedFromOthers
+              .map((p) => p.name)
+              .slice(0, 8)
+              .join('、')}${installedFromOthers.length > 8 ? ' 等' : ''}`,
+          )
+        : null,
+      (detail && detail.warnings && detail.warnings.length) || (detail && detail.myManifest && detail.myManifest.skipped && detail.myManifest.skipped.length)
+        ? h(
+            'div',
+            { className: 'pau-row-d', style: { marginTop: 10, color: 'var(--dsw-alias-warning,#a16207)' } },
+            [
+              ...((detail && detail.warnings) || []),
+              ...((detail && detail.myManifest && detail.myManifest.skipped) || []).map(
+                (item) => `${item.name}：${item.reason}`,
+              ),
+            ].slice(0, 5),
+          )
+        : null,
+    );
+
     const historyCard = h(
       'div',
       { className: 'pau-card' },
@@ -542,6 +799,7 @@ function makePanel(React) {
       masterCard,
       policyCard,
       pluginsCard,
+      shareCard,
       restartCard,
       historyCard,
     );