dsh-panel-updater 0.0.0-stage → 1.0.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-updater contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,113 @@
1
- # Temporary Holding Version
1
+ # 更新器 / Updater
2
+
3
+ `dsh-panel-updater` · **v1.0.0** · MIT
4
+
5
+ ```powershell
6
+ dsh plugin add dsh-panel-updater
7
+ ```
8
+
9
+ 装好后左侧栏会出现「更新器」图标。
10
+
11
+ 左侧栏的更新器入口。每次打开面板,它都会把**已安装插件**与**插件源**一起检索一遍,发现新版本就静默更新;任何一步出错都会在侧栏图标上留下红点,并在面板里写明出错阶段、对象与原始诊断。
12
+
13
+ ## 它是怎么跑起来的
14
+
15
+ 1. **宿主半(`lib/index.js`)** 通过 `pluginManager.listBundles()` 读出 profile 拥有的每个插件包。
16
+ 2. 对每个包向包源查询 `pluginManager.listVersions()`;同时读取 `pluginMarket` 里配置的每个插件源索引,按包名比对源里的默认版本。
17
+ 3. 两端取较高版本,若高于已装版本,就直接调用 `pluginManager.updateBundle()` **静默更新**,不再询问。
18
+ 4. 全流程结果发布在两条回环地址路由上:`GET /api/dsh-updater/status`、`POST /api/dsh-updater/check`。
19
+
20
+ 检查有三个触发点:
21
+
22
+ - **打开面板**(`POST /check`):完整检索 + 立即安装。路由最多等 12 秒就先把当前快照答回来,剩下的由面板轮询跟进,所以面板不会一直转圈。
23
+ - **宿主启动后约 8 秒、以及之后每 120 分钟**:同样完整检索并安装。定时器是在插件激活期间创建的,会继承那次激活留下的 HMR 事务;`updateBundle` 拒绝在事务里嵌套开启新事务,所以这条路径先用 `AsyncLocalStorage.exit` 离开事务再跑。这个能力**每次触发时重新解析**——激活那一刻 `hmr` 服务可能还没挂好,用快照会把此后所有后台周期永久降级。
24
+ - **降级路径**:若运行时确实拿不到该能力(HMR 服务在、但内部存储不可达),后台只做检索,把可更新的包标成「下次打开面板时安装」,安装交给打开面板那一次。这是唯一不会自动安装的情形。
25
+
26
+
27
+ ## 在哪里看到它
28
+
29
+ - 左侧栏图标:正常是灰色循环箭头;**更新失败是红点,只有提示是黄点**;用户自己触发的检索进行中显示品牌色小点(后台定时检查不闪)。
30
+ - 点击图标打开中央面板:
31
+ - 顶部:上次检查时间(含这一轮的触发来源:启动检查 / 后台自检 / 打开面板)与「立即检查」;
32
+ - **后台自检设置卡**:自动检查开关、检查间隔(15 分钟 ~ 12 小时)、启动时检查、发现新版本自动安装。**每次改动立即保存**,宿主随即重排定时器,不需要重启。设置存放在 profile 目录的 `dsh-updater.settings.json`。
33
+ - 汇总行:已检查 / 已更新 / 最新 / 未核对 / 问题;
34
+ - **问题区**:红色是真正挡住更新的事(更新失败、源查询失败),黄色是不影响更新的提示(插件源连不上)。每条都显示「阶段 · 对象 · 原因」,诊断原文收进可展开的「查看诊断」;每条右侧带修复按钮——红色条目给「重试」,黄色条目给「重试源」;
35
+ - **插件表按来源分组**:云端安装 / 本地链接 / Git 副本 / 本插件;组内按「坏了 → 缺依赖 → 未核对 → 有更新 → 其余」排序;
36
+ - 每个插件行显示:名称(点开介绍页)、当前版本、最新版本、状态,以及第二行的**扩展加载状态**(`N 个扩展正常` / `N 个扩展未加载`)、**缺失依赖**、该包声明的 DSH 版本要求;
37
+ - 每行右侧按钮:**升级**(任何时候都能点,已最新会直接告诉你)、**修复**(有扩展加载失败时出现,重新挂载失败的 Loader 行)、**装依赖**(缺的 peer 恰好是市场里的 bundle 时出现)、**仓库**、**源**(本地安装显示「本地」并把路径放进悬停提示);
38
+ - 插件源表:每个索引是否可用、抓到多少条目;不可用时就地给「重试源」。市场服务未启用时直接说明。
39
+
40
+ ## 依赖与扩展检查
41
+
42
+ - **扩展**:读 `pluginManager.listPlugins()` 的真实 `fiberPhase` 与 `diagnostic`,按 `bundle.rows[].entryId` 归到每个插件名下。有 failed 的行直接标红,并提供「修复」——对该行 disable/enable 重挂;整包没有具体失败行时,退回重挂整个 bundle。更新器**拒绝对自身**执行任何操作。
43
+ - **依赖**:读每个包自己的 `package.json` 的 `peerDependencies`,并用 `peerDependenciesMeta` **区分必需与可选**:
44
+ - 必需缺失 → 黄色提示,参与排序,可装(若在市场里);
45
+ - 可选缺失(例如 `dsh-connect-workbuddy` 的 `@earendil-works/pi-ai`,声明为 `optional: true`)→ 只说明「只影响对应的附加功能」,不报警、不参与排序。
46
+ - `react`、`react-dom`、`cordis`、`dsh`、所有 `@deepseek-ai/*` 视为安装已提供。
47
+ - 缺依赖时展开行内「这是什么意思」:解释 peer 依赖与本体的关系、为什么缺、影响范围,并给出可直接复制的命令:
48
+ ```
49
+ cd "<profile 目录>"
50
+ pnpm add <缺失的包>
51
+ ```
52
+ - 只有**同时出现在插件市场索引里**的依赖才有「装依赖」按钮;普通库无法作为 bundle 安装,给按钮就是骗人。
53
+ - **npm 别名安装**(如 `dsh-our-free-model@npm:@ebony-vinyl/dsh-our-free-model@2.8.5`):`listVersions` 只服务已安装的依赖名,别名包无法自动核对。这类行标注「npm 别名安装,需手动升级」,并把「源」链接指向**真实发布包**的页面。
54
+
55
+ ## 同步到其他设备:同步码
56
+
57
+ 面板里的「同步码」卡是最轻量的跨设备方式,不需要账号、网盘或文件:
58
+
59
+ 1. 在已配置好的设备上点「生成同步码」——生成一段 `DSHU1-…` 的码,并自动复制到剪贴板。
60
+ 2. 用聊天工具(微信/QQ 发给自己的「文件传输助手」)、系统云剪贴板、U 盘等任意方式把它带到另一台设备。
61
+ 3. 在另一台设备打开更新器,粘贴到输入框,点「导入同步码」。
62
+ 4. 出现勾选列表:全选 / 单个勾选 / 取消 → 「确认安装 N 项」。取消则列表保留,每项标注「未安装」,可「重新导入」。
63
+
64
+ 细节:
65
+
66
+ - 码里是压缩过的插件清单(名称、版本、安装来源、平台声明)与后台自检设置;12 个插件约 300–500 字符。
67
+ - 浏览器支持 `CompressionStream` 时用 `DSHU1-`(压缩),否则自动退回 `DSHU0-`(未压缩,更长但同样可用)。
68
+ - **平台过滤**:码里带每个插件的 `dsh.compatibility.profiles` 与客户端平台声明;手机端导入时,桌面专属插件会被禁用勾选并标注「当前设备不支持」,不会被装上。
69
+ - 本地路径安装(`file:` / `link:`)的插件标为「需手动放置」,不会尝试远程安装。
70
+
71
+ ### 账号同步(保留,非云端)
72
+
73
+ 账号卡仍可用:以登录账号为键,把快照写在本机 `$DSH_HOME/updater-sync/<账号ID>/setup.json`。**DSH 没有云端配置存储**,快照不会上传;只有把该目录放进 OneDrive / 坚果云等同步盘,多台设备才会自动共享。卡片上会检测并明确显示属于哪种情况。
74
+
75
+
76
+
77
+ ## 源连不上时会自己修
78
+
79
+ - 每个源的第一页最多试 2 次(间隔 0.5s),不是一次失败就上报。
80
+ - 缓存里上一次的失败**不会短路**下一次读取——源恢复了,警告会自己消失。
81
+ - 「重试源」是后台任务:接口 6ms 就返回,面板显示「重试中…」并轮询结果;它只重抓源,不重查 12 个包的版本,所以不会拖住整个面板。
82
+ - 源失败只是**黄色提示**:插件版本始终按 npm 源核对,更新功能不受影响,面板上会直接写明这一点。
83
+
84
+
85
+ ## 边界与限制
86
+
87
+ - **不更新自己**:`dsh-updater` 自身永远跳过,避免替换正在运行的模块;动作接口也拒绝对自身操作。
88
+ - **本地安装的包**(`file:` 链接)没有可拉取的源,记为「跳过」而不是错误。
89
+ - **Git 副本**只随仓库更新,面板里标为「Git 副本」,不算失败。
90
+ - 更新完成后若宿主提示需要重启,面板顶部会出现「刷新页面后生效」提示。
91
+ - **后台自检由用户在面板里设置**(开关 / 5 分钟~12 小时 / 启动检查 / 自动安装),改动即时保存到 profile 的 `dsh-updater.settings.json` 并重排定时器。
92
+ - **打开面板不触发检查**:只读取已有报告,避免每次点进来就等一整轮。
93
+ - 路由只接受回环地址请求,非本机直接 403。
94
+
95
+ ## 开发自检
96
+
97
+ 客户端半运行在浏览器的模块表里,本地不会执行到任何组件;一个未声明的变量就会让整个面板被 slot 错误边界吞掉(表现为黑屏)。改完客户端必须跑一次渲染烟测:
98
+
99
+ ```powershell
100
+ node tools/client-smoke.mjs dsh-updater/client.js
101
+ ```
102
+
103
+ 它用桩 React + 假 Host 报告把每个注册的组件真正调用一遍(含子组件与每一行)。也可以喂真实报告:
104
+
105
+ ```powershell
106
+ # 真实数据
107
+ Invoke-RestMethod http://127.0.0.1:<port>/api/dsh-updater/status |
108
+ ForEach-Object { $_.report | ConvertTo-Json -Depth 12 } | Set-Content report.json
109
+ node tools/client-smoke.mjs dsh-updater/client.js report.json
110
+ ```
111
+
112
+ 只有输出 `PASS: N seat(s), M component call(s)` 才说明每个座位都能渲染;任一组件抛错会打印组件名与堆栈并以非零码退出。
2
113
 
3
- 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.