背景:qiudl 分支(0.4.9-rc.2,用户原本在用的)有云状态功能——状态落在一个 独立 git 仓(~/Library/Application Support/dsh-worktable-state/),由 launchd 每 5 分钟 commit+push。Gitea 0.5.x 线没有这个功能,只有 DSH_HOME 下的单文件 镜像(worktable-state.json)。升级到 0.5.3 后两处路径不同,用户 14 个工作台 布局在界面上「消失」(数据本身还在那个 git 仓里)。 改法(不移植 976 行云状态代码,改走配置指针): - 宿主侧 /api/worktable/state 的文件路径改为优先取本机配置 03_local/local.json 的 cloudStatePath(指向那个 git 仓),未配置时回落到 DSH_HOME/worktable-state.json(与旧行为一致) - 新增 localConfigPaths / readLocalConfigField:候选链含环境变量 DSH_WORKTABLE_LOCAL_DIR、插件根相对 03_local、DSH_HOME/03_local - 客户端兼容旧 updatedAt 形态:旧线写 ISO 字符串,本线写毫秒数字,两种都认 (否则指向旧文件后永远判「宿主不比本地新」而不回填) 这样云状态写入自动进 git 仓,每次变更都有提交历史,launchd 继续 push 到远端。 版本 0.5.3-local.2 -> 0.5.3-local.3 验证:build 通过;client-factory-gate 10/10;7 个兼容回归 105/105; 配置解析链在本机实测命中 <DSH_HOME>/03_local/local.json -> 云状态 git 仓路径
5.1 KiB
本地补丁:工作台状态镜像到宿主侧
基于上游 Aisland-SJL/dsh-worktable v0.5.1,本地版本号 0.5.3-local.3。
为什么打这个补丁
桌面端宿主启动参数写死 --port 0(@deepseek-ai/dsh-slark-desktop-host 的
windows-startup.js:--profile web --no-open --host 127.0.0.1 --port 0),每次启动端口随机。
而工作台把项目/布局/绑定存在 localStorage(dsh.worktable.projects.v1、dsh.worktable.view.v1),
媒体存 IndexedDB —— 浏览器按「来源」隔离存储,端口一变就是另一个空库。
现象:新建的工作台,重启后消失。
改了什么
01_content/src/index.ts:新增路由GET/POST /api/worktable/state- 文件位置:
<DSH_HOME>/worktable-state.json(走resolveDshHomeSafe()) - GET 读回;POST 先读旧文件、按 key 合并、再原子写入(
.tmp-<pid>-<ts>→ rename) - 走宿主既有鉴权(
requestRejection),与/api/worktable/file等私有路由一致
- 文件位置:
01_content/src/client/hostState.ts(新增):宿主镜像的读/写、400ms 防抖合并、退避重试01_content/src/client/index.tsx:loadView/loadProjects抽出normalizeView/normalizeProjects,本地存档与宿主镜像共用校验persistView/persistProjects额外写dsh.worktable.savedAt.v1并把状态排进宿主镜像- 挂载时拉宿主镜像,只有
updatedAt > 本地 savedAt才回填,避免旧镜像盖掉刚改的内容 pagehide/beforeunload立即冲刷
两条数据安全约束(0.5.2-local.6 补的,来自真实事故)
事故:拖了一下面板(只改了 view),客户端 POST 的半截状态把整个文件替换,projects 被抹掉;
紧接着重启,客户端读宿主失败又用空状态覆盖了一次。
- 写入按 key 合并:服务端读旧文件再
{ ...previous, ...incoming },只带view的写入不会伤到projects。 - 读不到就不写:
loadHostState()带退避重试(0/300/700/1200/2000/3000ms)。 返回{ reachable: false }时调用staysReadOnly(),整场会话都不写镜像 —— 宁可这次只在本地,也不拿空状态覆盖。 - hydration 成功后
markHydrated(权威内容)整体替换待写队列。 事故根因:首屏「控制室自愈」effect 早于异步恢复跑完,把空项目塞进队列; 旧实现只是合并队列,那份空值留了下来,恢复后 0.5 秒就被写回。必须整体替换。 - 宿主镜像不比本地新时不主动落盘,等用户真的改动再写。
logs/worktable-state.log 只在异常时记一行(鉴权被拒 / 项目数量变少),正常保存不写,可长期保留。
改动这三条时注意:hydrated 为 false 期间 queueHostSave 只累积不发送,这是首屏默认值的闸门,别去掉。
覆盖范围
- 覆盖:项目、布局、绑定、项目文件夹、视图/外观设置
- 不覆盖:图库媒体(照片)仍在 IndexedDB,换端口照样丢
兼容声明
0.2.0-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.5 || 0.2.2-alpha.2
宿主不在这个范围里时,dsh plugin add 会直接拒绝并回滚。换宿主版本要同步改
package.json 的 engines.dsh和dsh.compatibility.dsh / dshReleases,三处一起改。
构建 / 安装
cd 01_content
npm install
npm run build # lib/index.js + lib/client.js
npm pack # 产出 dsh-worktable-<version>.tgz(7 文件,无 .map)
发到 Gitea Release 后(xiaoqu/dsh-worktable):
dsh plugin --profile web add "https://gitea.ququclean.com/xiaoqu/dsh-worktable/releases/download/v<version>/dsh-worktable.tgz"
装完必须完全退出宿主再重开。
注意:升级到新版本时,别先删旧 Release —— profile 里还指着旧地址,pnpm 解析依赖会 404。 正确顺序是:先装新版(profile 依赖换成新地址)→ 再把旧 Release 删掉。
升级官方版时的注意
上游出 0.5.2 及以上时,本地补丁会被覆盖,需要把上面的改动重新合并到新版本再打包。 如果上游自己解决了「桌面端随机端口 + localStorage」,这个补丁就可以直接丢掉。
版本历史
| 版本 | 内容 |
|---|---|
| 0.5.2-local.1 | 状态镜像首版;只声明兼容到 0.2.1-rc.5 |
| 0.5.2-local.2 | 兼容声明加入 DSH 0.2.2-alpha.2(宿主升级后安装被拒) |
| 0.5.2-local.6 | 修数据安全:写入按 key 合并 + 读不到不写,修复空状态覆盖镜像 |
| 0.5.3-local.1 | REQ-20261117-0013:单标签窗格隐藏标签栏(原只对控制室生效),关闭入口移到窗格标题条,标题改显示当前标签名 |
| 0.5.3-local.2 | REQ-20261117-0013:收起态 rail 限制 8 个图标,其余进「⋯」菜单(原先四类全平铺无上限) |
| 0.5.3-local.3 | REQ-20261117-0013:状态文件路径改为优先取本机 03_local/local.json 的 cloudStatePath(指向独立 git 仓),恢复「云状态 + git 历史」;客户端兼容旧 ISO 串形态的 updatedAt |