xrkh-better-sidebar 0.20.9 → 0.20.11

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/README.md CHANGED
@@ -1,289 +1,302 @@
1
- # xrkh-better-sidebar
2
-
3
- > **读者**:XRK-Harness 终端用户 · 集成者
4
-
5
- XRK-Harness(`xrkh`)标准侧边栏插件:资源管理器 · 编辑器 · 终端 · Git · 浏览器等工作台,按会话隔离。
6
- Host 侧 `/sidebar/*` 由产品 Host 原生挂载(`createSidebarPublicHandler`);本包提供 **client 半包**。`src/index.ts` 的 Cordis host 半包仅供非 XRKH 的 Cordis profile;**不要**在 XRKH 上再挂 host 抢同一前缀。
7
-
8
- ## 安装
9
-
10
- 前置:`xrkh web` 或 `npx @xrkseek/harness-cli web`,Node ≥ 26。建议 Host **≥ 0.3.4**。推荐从 **npmjs** 安装:
11
-
12
- ```bash
13
- xrkh plugin add xrkh-better-sidebar@0.20.9
14
- xrkh restart
15
- ```
16
-
17
- 装完硬刷新浏览器(Ctrl+Shift+R)。建议 Host **≥ 0.7.19**(`LayoutInsets.detailsOpen` / 手机概况互斥)。
18
-
19
- 源码路径仍可用(非推荐):`git clone git@github.com:xrkseek/xrkh-better-sidebar.git` 后 `xrkh plugin add ./xrkh-better-sidebar`。
20
-
21
- ## 0.20.9
22
-
23
- - **手机概况互斥**:Host 打开概况 / Status 时隐藏展开 FAB、收起抽屉,并隐藏整个 `data-dsh-panel-host`,避免与概况关闭键抢角或挡住点按(读 `ctx.layout.insets.detailsOpen` + `phone`)。
24
- - **文件树**:监视刷新与变异路径更稳;打开文件 /「打开方式」工具栏收口。
25
- - 建议搭配 **XRK-Harness ≥ 0.7.19**。
26
-
27
- ## 0.20.7
28
-
29
- - **展开记忆**:侧栏 / 底栏开合在硬刷新、WebView 切后台时仍能保住(展开立刻落盘 + `pagehide` / `visibilitychange` 冲刷)。
30
- - **打开文件**:对话点开文件默认不再强开伴随资源树;编辑器工具栏可「打开方式」;树监视刷新更稳。
31
-
32
- ## 0.20.6
33
-
34
- - **手机下载**:二进制 / 图片 / PDF / 树菜单「下载」改走 fetch→blob→`<a download>`,避免 iOS / Android 上查询串路由只导航不落盘。
35
- - **手机抽屉**:窄屏全宽 + 左右安全区;开关按钮 44px 触控;下载链同样加大点按区。
36
-
37
- ## 0.20.5
38
-
39
- - 适配 Host **0.6.19** 图标表面:产品图标只保留 `IconXxxRegular` / `IconXxxMedium` 权重名,旧的 `IconXxx14` / `IconXxx16` 已从 `@xrkseek/client-ui-primitives` 移除。本插件客户端全部迁到 Regular,修复启动时 Sidebar 因 `undefined` 组件白屏(`Element type is invalid … Check the render method of Sidebar`)。
40
-
41
- ## 0.20.4
42
-
43
- - 修「文件不存在」:某些会话里点击对话中的文件路径会报 file miss(文件其实在)。根因是会话目录在
44
- `working_directory` / worktree / 隔离子代理下与客户端缓存的摘要不一致,客户端拿旧目录拼出了
45
- 错误的绝对路径。现在客户端统一以 Host 上报的会话目录为准,并对 chat 传来的路径做重定位。
46
- - 文件(editor)窗口右侧恢复**可开关的资源管理器面板**(VSCode 式):头部文件夹按钮切换显隐、
47
- 左缘分隔条拖拽调宽,展开/宽度按 tab 记忆(`meta.treeOpen` / `meta.treeWidth`);无路径的
48
- 「文件」窗口默认展开,文件窗口默认收起。
49
- - 点对话里的文件链接:在右侧打开该文件的同时**自动展开它所在窗口的资源管理器并定位高亮**该文件
50
- (展开祖先目录 + 滚动居中),与「在文件夹中显示」同一条 reveal 语义;打开的文件标签也会闪一下。
51
- - 「在文件夹中显示」:揭示会话工作目录,并打开无路径的「文件」窗口把该目录行染色定位。
52
- - 停靠资源管理器面板收尾:宽度上限与 CSS `max-width: 70%` 对齐(窄侧栏不再出现「拖不动、`aria-valuemax` 却报更宽」),
53
- `aria-valuemax` 跟随实测上限;右键/中键按分隔条不再开始拖拽;拖拽中指针捕获丢失(`lostpointercapture`)会中止拖拽;
54
- 只点击不移动不再误写 `meta.treeWidth`。
55
- - 修复「展开/收起」二次点击失效:文件夹按钮改读实时 `meta`,不再被闭包里的旧状态吞掉。
56
- - 修复 reveal 高亮被 hover 抹掉:鼠标划过刚被高亮的行时底色不再消失(`.explorerRow:not(.explorerRowRevealed):hover`)。
57
- - 新建文件 / 新建文件夹 / 重命名后**展开**父目录(原为切换:父目录已展开时会把它折叠起来,反而看不到新建的条目)。
58
- - 文件操作失败(新建 / 重命名 / 删除)改用专门的失败提示,不再复用「无法在外部打开」文案;二进制文件预览不再
59
- 同时显示编辑器与下载页两条重复的失败 notice。
60
- - 新增 `session-cwd` 客户端会话目录模块(统一以 Host 上报为准 + 路径重定位),补齐对应单测。
61
-
62
- ## 0.20.3
63
-
64
- - 对话交付物 / 提及点击打开文件时:展开祖先目录、短暂高亮**打开的文件标签**(此前只开编辑器、树默认收起看不到高亮)。
65
-
66
- ## 0.20.2
67
-
68
- - 图片预览 Ctrl/⌘+滚轮灵敏度修正:单次滚轮不再跳到 800%/1600%。
69
- - 自由窗口 z-index 提到 48(高于面板开关簇 45),重叠顶栏缝时可正常关闭。
70
- - 自由窗口 y 夹取尊重 Desktop 标题栏高度(`--xrk-desktop-chrome-height` / `--dsh-title-bar-strip`),避免钻到 chrome(z=55)下面点不到。
71
-
72
- ## 0.20.1
73
-
74
- - OOXML 高保真预览外置为独立包 `xrkh-better-sidebar-plugin-office`(AGPL);本包仅保留 `office-legacy` 下载兜底。
75
- - Side card →「添加预览插件」推荐目录收录 office 安装命令。
76
-
77
- ```bash
78
- xrkh plugin add xrkh-better-sidebar-plugin-office@0.1.1
79
- ```
80
-
81
- ## 0.20.0
82
-
83
- ### Office 文档预览(独立插件)
84
-
85
- 高保真 `.docx` / `.xlsx` / `.pptx` 预览由独立包
86
- `xrkh-better-sidebar-plugin-office` 提供(docx-preview / Univer /
87
- `@aiden0z/pptx-renderer`),通过 `ctx.betterSidebar.registerFileViewer`
88
- 注册,不进本包 client bundle。安装:
89
-
90
- ```bash
91
- xrkh plugin add xrkh-better-sidebar-plugin-office@0.1.0
92
- ```
93
-
94
- 或源码:`xrkh plugin add ./extensions/xrkh-better-sidebar-plugin-office`。
95
-
96
- 未安装时,OOXML 与旧格式(`.doc/.xls/.ppt` / ODF / RTF)一律走本包
97
- `office-legacy` 下载兜底。Side card →「添加预览插件」也可一键复制安装命令。
98
-
99
- ### 图片预览缩放
100
-
101
- - 图片预览支持 **Ctrl/⌘ + 滚轮** 以光标为中心缩放,拖拽平移,双击在「适应」
102
- 和 2x 之间切换,工具栏有「适应 / 100% / 下载」与实时百分比;`+` `-` `0` 快捷键。
103
- - 修复:React 17+ 把 `wheel` 注册为 passive listener,合成 `onWheel` 的
104
- `preventDefault()` 无效——Ctrl+滚轮会连带把整个应用页面一起缩放。改用原生
105
- `{ passive: false }` 监听抑制页面级缩放。
106
- - 缩放走 CSS `transform`(不触发布局),平移有 3px 阈值判定,避免误点击把图拖走。
107
-
108
- ### 文件树「在文件夹中显示」可见反馈
109
-
110
- - 修复「点了没反应」:右键菜单能正常弹出(实测过),但 reveal/open 的失败
111
- 被 catch 成 `console.error`,界面上零反馈。Host 侧 Windows 走
112
- `explorer.exe /select` 时也可能静默失败。现在失败会以可点击关闭的 notice
113
- 显示在树上,不再静默吞掉。
114
-
115
- ### 文件树文件操作(新建 / 重命名 / 删除)
116
-
117
- - Host 早已提供 `fs.mkdir` / `fs.delete`,但客户端此前完全没接——右键菜单里
118
- 根本没有这些项,只能看不能管。本轮接上并补齐 UI:
119
- - 目录右键:新建文件 / 新建文件夹;文件右键:重命名 / 删除(删除为危险项,
120
- 带名称确认)。
121
- - 取消 prompt 或留空名是 no-op,不会误创建 `dir/`;重命名同名也是 no-op。
122
- - 所有失败(权限 / 越界 / 占用)走同一条可见 notice,不静默。
123
- - `fs.rename` 用「读字节 → 写入新路径 → 删源」实现,复用已有路由承载的
124
- workspace fence,不为这一个功能给 Host 加新动词。
125
-
126
- ### 其它
127
-
128
- - 新增 `IconOfficeOutline16` 文件预览图标;OOXML 高保真预览外置为
129
- `xrkh-better-sidebar-plugin-office`,本包保留 `office-legacy` 下载兜底。
130
- - i18n:20 个语言字典补齐本轮全部新键(image* / office* / openExternalFailed /
131
- newFolder / rename / delete 等)。
132
- - 新增/更新测试:图片缩放 10 例、Office 组件 8 例、文件操作 10 例、OOXML 解析
133
- 34 例(含真实 LibreOffice/pptx 文件验证,缺 fixture 时自动跳过)。全量测试
134
- 未引入任何回归(基线红/绿保持一致)。
135
-
136
- ## 0.19.5
137
-
138
- - 修复底栏偶发空白(拖侧栏才出现):未测到中心列时 `left+right` 回退成零宽;改走 `--xrkh-center-*`,未测到前右侧回退为 workbench + Overview inset
139
-
140
- ## 0.19.4
141
-
142
- - 重新发布:npm 上 0.19.3 卡在 staged 未公开(E409),内容与 0.19.3 相同
143
-
144
- ## 0.19.3
145
-
146
- - 修复拖动 Host **概况** 时工作台 toggle 集群不跟手:跟 `details inset + workbench width` 停在主列右缘;拖拽中关闭 `right` 缓动
147
- - 删除已无消费者的 `data-*-sidebar-collapsed` body 标记与钉死视口右上角的冗余路径
148
-
149
- ## 0.19.2
150
-
151
- - 重新发布:npm 上 0.19.1 卡在 staged 未公开(E409),内容与 0.19.1 相同
152
-
153
- ## 0.19.1
154
-
155
- - 修复内部 SIDEBAR_SERVICE_VERSION 仍报 0.18.32 的疏漏(功能与 0.19.0 相同;npm 0.19.0 包内版本串未对齐)
156
-
157
- ## 0.19.0
158
-
159
- - 完善右侧工作台与 Host **概况(Overview)** 共存:toggle 集群始终按 `details inset + workbench width` 停在**主对话列右缘**,不再叠在概况顶栏
160
- - 完善展开/收起过渡:与 Host shell 共用 motion 时长与缓动;会话顶栏为 toggle 预留的 padding 跟随概况开合
161
- - 建议搭配 **XRK-Harness ≥ 0.5.9**(LayoutInsets / 概况 inset 契约)
162
-
163
- ## 0.18.30
164
-
165
- (相对未落地的 0.18.29:同批修复。npm 上 0.18.29 卡在 staged 未公开,以本号为准。)
166
-
167
- - 修复对话尾部文件行整个 slot 渲染崩溃(`Cannot read properties of undefined (reading 'modified')`)。**0.18.27 回归**:三条 lane 改造时把组件 prop 从宿主契约名 `matched` 改成了 `lanes`;ui-slots chain 始终把 selector 返回值注入为 `matched`(`ChainEntryProps`),同槽的 `@xrkseek/client-ui-deliverables` 也按 `matched` 读。改名后组件拿到 `undefined`
168
- - 组件侧:只认 `matched`;用 `isFileLanes` 校验形状;缺失/坏形状时从宿主一并展开的 owner 字段重算 lanes,不再直接读 `.modified`
169
- - 与宿主 Diff 卡共存:本轮已有 `workspace/changes` 卡时(按 closing `seq`,对齐宿主 `changesForClosing`)主动放弃 takeover,避免盖住 ChangedFiles;文件打开仍走 `workspaces.openPath` 拦截
170
- - 测例钉住「select 输出 → 宿主 prop 名 `matched` → 组件消费」整条边界(此前只断言注册元数据,改错名字也会绿灯)
171
- - 文件树:活动页心跳 1.2s→4s、隐藏 6s→12s;保存后 `nudgeTreeWatch` 立即拉一轮,少无感狂刷
172
-
173
- ## 0.18.28
174
-
175
- - 文件树增量自动刷新:AI 建/改/删文件后,已展开的树无感更新。Host 侧新增按 `sessionId` + 目录管理的非递归 `fs.watch` registry(per-subscriber 引用计数、单调 sequence + 有界 replay、watcher 失效自动重开),配 `fs.watch.sync`(只回「哪几层变了」+ 游标)与 `fs.tree.batch`(批量 listing + 可选 `statPaths`)
176
- - 客户端共享 watch broker:同一会话/cwd 的文件树与多个编辑器合并成一份订阅与一轮请求;活动页 ~1.2s、隐藏页 ~6s、失败退避 4s;健康时每 20 轮全量 sweep,有不可监听目录时 5 轮
177
- - 刷新语义:只替换真正变化的已加载层(`levelSignature` 比对,相同则跳过 setState),不显示 loading、不调 `refreshTick`、不物化未展开目录、不动展开/搜索/滚动/拖拽状态
178
- - 打开中文件的外部修改:`mtimeMs` 贯穿 `fs.read` → 渲染 → baseline;内容 clean 时静默重载,dirty 时绝不覆盖草稿,显示「文件已被外部修改,草稿未覆盖」提示条与刷新按钮;无 baseline 的 viewer 不循环重载
179
- - 修复:`fs.tree.batch` 的 listing/stat 回显改为调用方传入的原始路径(此前回显 Host 解析后的 realpath——symlink workspace root、Windows 大小写或分隔符规范化下,客户端的层级 key 与 stat 行会永久匹配不上,树看起来「不再刷新」)
180
- - 点击卡顿(静态定位):`TreePanel` 加 memo 渲染边界、树回调 `useCallback` 稳定化、`FileTree` 单次 `setData` 批量提交(原为逐层提交)、CodeMirror 语言包按语言 key 缓存
181
- - 测试环境:`vitest.config.ts` 加 `resolve.dedupe: ['react', 'react-dom']`(插件与宿主根各装一份 React,经 `client-ui-primitives` 跨界渲染时全部 UI 测试死于 `Invalid hook call`)
182
- - i18n:19 个语言字典补齐 7 个漏键(`fileChangedOnDisk` / `laneModified` / `laneDeleted` / 四个 `viewer*`)
183
- - 冗余清理:删除无消费者的 `onDegraded` 钩子、`mergeLevel` 导出与重复的 `messageOf`;`locales.spec.ts` 里测 0.18.0 已删除的 `attachBetterLocale` 覆盖层协议的残留一并清掉
184
-
185
- ## 0.18.27
186
-
187
- - 对话尾部文件行:按「本次改动 / 本次删除 / 本次产出」三条 lane 渲染(此前只有一条「本次产出」,改动与删除被丢弃)
188
- - 修复根因:接管 `conversation.chat.turnTail` 时只挑 `path`、丢掉 Turn 数据里的 `op`,等于把内核已有的 lane 压平;删除的 chip 置灰划线、不可点(文件已不存在)
189
- - 无 `op` 的旧会话回落:`workspace/changes` 行数启发式(0 增有删 → 删除,0 删有增 → 产出,其余 → 改动)
190
-
191
- ## 0.18.26
192
-
193
- - 终端:挂起唤醒后画布空白时 fit/refresh;网格仍死则 remount 并重挂 PTY;关闭 `allowTransparency` 减轻 GPU 挂起后整页空白
194
- - Desktop:忽略塌缩的 `visualViewport` 当键盘 inset(避免布局推挤空白条与 `overflow: clip` 裁切面板)
195
- - 偏好默认与 Host 对齐:`openByDefault` / `bottomPanelAutoTerminal` 默认关
196
- - 布局:双写 `data-xrkh-sidebar-*` 与 `--xrkh-workbench-*`;存储键 `xrkh-sidebar:v1`(迁移旧 `dsh-sidebar:v1`)
197
-
198
- ## 0.18.21
199
-
200
- - `openTab({ type: 'editor' })` 固定落到侧栏分栏(`splits`),不因 `activePane` 在底栏而撑开底部面板(避免聊天开文件先出空白底栏 / 自动终端)
201
-
202
- ## 0.18.20
203
-
204
- - 拖拽分栏时合并 resize(一帧一次、跳过无变化),避免 Windows ConPTY 反复重打「版本」MOTD
205
- - Host 短暂不可用(5xx / 空 1006)时软重连更久,不把已绘出的 MOTD 盖上致命横幅
206
- - SSE 与 input/resize POST 不再共用 AbortController,关流时不误取消在途控制请求
207
- - 载波仍同 0.18.19:页面同源 `xrk-app://app`(池隔离归 Desktop/Face,不在本插件翻)
208
-
209
- ## 0.18.19
210
-
211
- - Desktop 终端:SSE/POST 回到页面同源 `xrk-app://app`(去掉会 `Failed to fetch` 的 `xrk-app://stream` 分裂与回退冗余)
212
-
213
- ## 0.18.18
214
-
215
- - 轨图标:面板展开时贴齐 34px 页签条(`+3`),收起时仍对齐会话标题行(`+14`),不再下偏
216
- - Desktop 终端:SSE 不再带 `Accept`;`stream` 主机打不开时曾回退 `app`(已由 0.18.19 去掉回退)
217
-
218
- ## 0.18.17
219
-
220
- - 右侧面板顶距改为单一 `top`(`--dsh-title-bar-strip` → `--xrk-desktop-chrome-height`),去掉 `padding-top` 叠 chrome,修复 Desktop 页签上方空带
221
-
222
- ## 0.18.14
223
-
224
- - `title-bar-compat`:`--dsh-title-bar-strip` 已含 Desktop chrome,不再叠加 `--xrk-desktop-chrome-height`(侧栏轨图标不再比标题栏矮一截)
225
- - toggle cluster:与会话标题行垂直对齐(`+14px` · `align-items: center`)
226
- - 启动期 panel/FAB 隐藏:去掉插件侧重复 CSS,统一由内核 `data-xrk-booting` 负责
227
-
228
- ## 0.18.12
229
-
230
- - 启动 splash(`data-xrk-booting`):隐藏 panel-host / FAB,避免与 HARNESS 启动页叠层
231
- - 会话头「Session log」:有 toggle cluster 时始终右缩,展开动画中不再被按钮挡住
232
- - 动效:主题 token 冷启动回退 380ms / cubic-bezier,展开收起不再僵硬跳切
233
- - Desktop chrome:右侧面板与 FAB 避开 `--xrk-desktop-chrome-height`
234
-
235
- ## 0.18.11
236
-
237
- - 文件页:`openTab({ type: 'editor' })` 聚焦已种子的 files-home,不再并排冒出第二个「文件」标签
238
- - `applyDedupe`:`dedupeKey` 返回 `undefined` 时仍按同 cohort 去重(与 pathless 编辑器一致)
239
- - 底栏首次展开:若已有 UI 终端则跳过自动再开一个
240
-
241
- ## 0.18.10
242
-
243
- - Desktop(`xrk-app://`):终端改走 Host HTTP SSE + POST(`/sidebar/api/pty/*`),不再对无 listen 的私有 Host 死循环 WebSocket 重连
244
- - 无边框窗口:右侧面板留 2px 边缘,便于 Electron 命中缩放
245
-
246
- ## 0.18.9
247
-
248
- - `openTab`:当前会话下任意打开(含仅 `type` 的 Files / +菜单)都会展开已折叠侧栏,调用方无需再自行 `togglePanel`
249
-
250
- ## 0.18.3
251
-
252
- - Client fiber 注入 `layout`(与 `ui-sidebar` 同序):等 `ui-layout` 声明中心栏后再挂侧栏拦截,避免 Host ≥0.3.4 上 `conversation` slot 竞态
253
- - `xrk.client.inject` 补 `@xrkseek/client-ui-layout`;文档 Host 基线改为 **≥ 0.3.4**
254
-
255
- ## 0.18.2
256
-
257
- - Files 主页签随 locale;轻量媒体预览;默认打开侧栏
258
-
259
- ## 0.18.1
260
-
261
- - `subagents.live`:兼容嵌套 `tool` 与旧版扁平 `tool` wire,避免子代理活动预览崩溃
262
- - 与 Host 原生 `/sidebar/*`(嵌套 live 形状)对齐
263
-
264
- ## 0.18.0
265
-
266
- - XRKH 原生:去掉第三方双轨(旧 manifest · better-locale · 旧安装脚本 · 市场目录)
267
- - peer 仅 `@xrkseek/*` + React;工具类型走 `@xrkseek/xrk-tools` / `xrk-settings`
268
- - 无 Side Chat;子代理走 Host Face + `subagents.live` / `jobs.*`
269
- - 空 curated 插件目录(社区扩展不随包捆绑)
270
-
271
- ## 契约
272
-
273
- | 项 | 说明 |
274
- |----|------|
275
- | npm | `xrkh-better-sidebar` |
276
- | 仓库 | `xrkseek/xrkh-better-sidebar` |
277
- | 形态 | **仅 client 半包**(`package.json` → `xrk.client` → `lib/client.js`) |
278
- | 注入 | `client-runtime` · `client-locale` · `client-ui-slots` · `client-ui-layout` · `client-ui-conversation` · `client-modules` |
279
- | Host | **产品 Host 拥有** `/sidebar/api` · `/sidebar/file|upload|html|bundle` · `/sidebar/ws/terminal` 等;本包不在 XRK 上挂 Cordis host 半包抢同一前缀 |
280
- | 子代理 / 任务 | 走 Host Face + `/sidebar/api` 的 `subagents.live` · `jobs.*`(勿再实现 Side Chat) |
281
-
282
- 契约细则见 Harness 教科书 [community-plugins.md](https://github.com/xrkseek/XRK-harness/blob/main/docs/community-plugins.md)「侧栏插件契约」。
283
-
284
- ## 开发
285
-
286
- ```bash
287
- pnpm install
288
- pnpm bundle
289
- ```
1
+ # xrkh-better-sidebar
2
+
3
+ > **读者**:XRK-Harness 终端用户 · 集成者
4
+
5
+ XRK-Harness(`xrkh`)标准侧边栏插件:资源管理器 · 编辑器 · 终端 · Git · 浏览器等工作台,按会话隔离。
6
+ Host 侧 `/sidebar/*` 由产品 Host 原生挂载(`createSidebarPublicHandler`);本包提供 **client 半包**。`src/index.ts` 的 Cordis host 半包仅供非 XRKH 的 Cordis profile;**不要**在 XRKH 上再挂 host 抢同一前缀。
7
+
8
+ ## 安装
9
+
10
+ 前置:`xrkh web` 或 `npx @xrkseek/harness-cli web`,Node ≥ 26。建议 Host **≥ 0.3.4**。推荐从 **npmjs** 安装:
11
+
12
+ ```bash
13
+ xrkh plugin add xrkh-better-sidebar@0.20.11
14
+ xrkh restart
15
+ ```
16
+
17
+ 装完硬刷新浏览器(Ctrl+Shift+R)。建议 Host **≥ 0.7.19**(`LayoutInsets.detailsOpen` / 手机概况互斥)。
18
+
19
+ 源码路径仍可用(非推荐):`git clone git@github.com:xrkseek/xrkh-better-sidebar.git` 后 `xrkh plugin add ./xrkh-better-sidebar`。
20
+
21
+ ## 0.20.11
22
+
23
+ - **设置页版本**:徽章读 `package.json`,不再硬编码 semver。
24
+ - **配置热更**:Side card 订阅共享 store;外部写入 / `settings/document-updated` 会刷新 prefs 与 revision。
25
+ - **打开方式 · 三轴**(承接 0.20.10):APK 薄壳 / 远程 Web / 窄屏 chrome 分开判。
26
+ - 推荐 office 预览插件 **`xrkh-better-sidebar-plugin-office@0.1.2`**(手机 blob 下载 · 窄屏触控)。
27
+ - 建议搭配 **XRK-Harness ≥ 0.7.20**。
28
+
29
+ ## 0.20.10
30
+
31
+ - **打开方式 · 三轴**:APK 薄壳(`XrkShell`)/ 远程 Web(`!loopback`)/ 窄屏 chrome(`phone`)分开判。APK 不画 Cursor/VS Code 列表(走系统分享与「下载」);手机浏览器连服务器同样隐藏;本机窄窗仍可 Face 探测编辑器,只改成扁平菜单。
32
+ - 建议搭配 **XRK-Harness ≥ 0.7.19**。
33
+
34
+ ## 0.20.9
35
+
36
+ - **手机概况互斥**:Host 打开概况 / Status 时隐藏展开 FAB、收起抽屉,并隐藏整个 `data-dsh-panel-host`,避免与概况关闭键抢角或挡住点按(读 `ctx.layout.insets.detailsOpen` + `phone`)。
37
+ - **文件树**:监视刷新与变异路径更稳;打开文件 /「打开方式」工具栏收口。
38
+ - 建议搭配 **XRK-Harness ≥ 0.7.19**。
39
+
40
+ ## 0.20.7
41
+
42
+ - **展开记忆**:侧栏 / 底栏开合在硬刷新、WebView 切后台时仍能保住(展开立刻落盘 + `pagehide` / `visibilitychange` 冲刷)。
43
+ - **打开文件**:对话点开文件默认不再强开伴随资源树;编辑器工具栏可「打开方式」;树监视刷新更稳。
44
+
45
+ ## 0.20.6
46
+
47
+ - **手机下载**:二进制 / 图片 / PDF / 树菜单「下载」改走 fetch→blob→`<a download>`,避免 iOS / Android 上查询串路由只导航不落盘。
48
+ - **手机抽屉**:窄屏全宽 + 左右安全区;开关按钮 44px 触控;下载链同样加大点按区。
49
+
50
+ ## 0.20.5
51
+
52
+ - 适配 Host **0.6.19** 图标表面:产品图标只保留 `IconXxxRegular` / `IconXxxMedium` 权重名,旧的 `IconXxx14` / `IconXxx16` 已从 `@xrkseek/client-ui-primitives` 移除。本插件客户端全部迁到 Regular,修复启动时 Sidebar 因 `undefined` 组件白屏(`Element type is invalid … Check the render method of Sidebar`)。
53
+
54
+ ## 0.20.4
55
+
56
+ - 修「文件不存在」:某些会话里点击对话中的文件路径会报 file miss(文件其实在)。根因是会话目录在
57
+ `working_directory` / worktree / 隔离子代理下与客户端缓存的摘要不一致,客户端拿旧目录拼出了
58
+ 错误的绝对路径。现在客户端统一以 Host 上报的会话目录为准,并对 chat 传来的路径做重定位。
59
+ - 文件(editor)窗口右侧恢复**可开关的资源管理器面板**(VSCode 式):头部文件夹按钮切换显隐、
60
+ 左缘分隔条拖拽调宽,展开/宽度按 tab 记忆(`meta.treeOpen` / `meta.treeWidth`);无路径的
61
+ 「文件」窗口默认展开,文件窗口默认收起。
62
+ - 点对话里的文件链接:在右侧打开该文件的同时**自动展开它所在窗口的资源管理器并定位高亮**该文件
63
+ (展开祖先目录 + 滚动居中),与「在文件夹中显示」同一条 reveal 语义;打开的文件标签也会闪一下。
64
+ - 「在文件夹中显示」:揭示会话工作目录,并打开无路径的「文件」窗口把该目录行染色定位。
65
+ - 停靠资源管理器面板收尾:宽度上限与 CSS `max-width: 70%` 对齐(窄侧栏不再出现「拖不动、`aria-valuemax` 却报更宽」),
66
+ `aria-valuemax` 跟随实测上限;右键/中键按分隔条不再开始拖拽;拖拽中指针捕获丢失(`lostpointercapture`)会中止拖拽;
67
+ 只点击不移动不再误写 `meta.treeWidth`。
68
+ - 修复「展开/收起」二次点击失效:文件夹按钮改读实时 `meta`,不再被闭包里的旧状态吞掉。
69
+ - 修复 reveal 高亮被 hover 抹掉:鼠标划过刚被高亮的行时底色不再消失(`.explorerRow:not(.explorerRowRevealed):hover`)。
70
+ - 新建文件 / 新建文件夹 / 重命名后**展开**父目录(原为切换:父目录已展开时会把它折叠起来,反而看不到新建的条目)。
71
+ - 文件操作失败(新建 / 重命名 / 删除)改用专门的失败提示,不再复用「无法在外部打开」文案;二进制文件预览不再
72
+ 同时显示编辑器与下载页两条重复的失败 notice。
73
+ - 新增 `session-cwd` 客户端会话目录模块(统一以 Host 上报为准 + 路径重定位),补齐对应单测。
74
+
75
+ ## 0.20.3
76
+
77
+ - 对话交付物 / 提及点击打开文件时:展开祖先目录、短暂高亮**打开的文件标签**(此前只开编辑器、树默认收起看不到高亮)。
78
+
79
+ ## 0.20.2
80
+
81
+ - 图片预览 Ctrl/⌘+滚轮灵敏度修正:单次滚轮不再跳到 800%/1600%。
82
+ - 自由窗口 z-index 提到 48(高于面板开关簇 45),重叠顶栏缝时可正常关闭。
83
+ - 自由窗口 y 夹取尊重 Desktop 标题栏高度(`--xrk-desktop-chrome-height` / `--dsh-title-bar-strip`),避免钻到 chrome(z=55)下面点不到。
84
+
85
+ ## 0.20.1
86
+
87
+ - OOXML 高保真预览外置为独立包 `xrkh-better-sidebar-plugin-office`(AGPL);本包仅保留 `office-legacy` 下载兜底。
88
+ - Side card →「添加预览插件」推荐目录收录 office 安装命令。
89
+
90
+ ```bash
91
+ xrkh plugin add xrkh-better-sidebar-plugin-office@0.1.2
92
+ ```
93
+
94
+ ## 0.20.0
95
+
96
+ ### Office 文档预览(独立插件)
97
+
98
+ 高保真 `.docx` / `.xlsx` / `.pptx` 预览由独立包
99
+ `xrkh-better-sidebar-plugin-office` 提供(docx-preview / Univer /
100
+ `@aiden0z/pptx-renderer`),通过 `ctx.betterSidebar.registerFileViewer`
101
+ 注册,不进本包 client bundle。安装:
102
+
103
+ ```bash
104
+ xrkh plugin add xrkh-better-sidebar-plugin-office@0.1.2
105
+ ```
106
+
107
+ 或源码:`xrkh plugin add ./extensions/xrkh-better-sidebar-plugin-office`。
108
+
109
+ 未安装时,OOXML 与旧格式(`.doc/.xls/.ppt` / ODF / RTF)一律走本包
110
+ `office-legacy` 下载兜底。Side card →「添加预览插件」也可一键复制安装命令。
111
+
112
+ ### 图片预览缩放
113
+
114
+ - 图片预览支持 **Ctrl/⌘ + 滚轮** 以光标为中心缩放,拖拽平移,双击在「适应」
115
+ 和 2x 之间切换,工具栏有「适应 / 100% / 下载」与实时百分比;`+` `-` `0` 快捷键。
116
+ - 修复:React 17+ 把 `wheel` 注册为 passive listener,合成 `onWheel` 的
117
+ `preventDefault()` 无效——Ctrl+滚轮会连带把整个应用页面一起缩放。改用原生
118
+ `{ passive: false }` 监听抑制页面级缩放。
119
+ - 缩放走 CSS `transform`(不触发布局),平移有 3px 阈值判定,避免误点击把图拖走。
120
+
121
+ ### 文件树「在文件夹中显示」可见反馈
122
+
123
+ - 修复「点了没反应」:右键菜单能正常弹出(实测过),但 reveal/open 的失败
124
+ 被 catch 成 `console.error`,界面上零反馈。Host 侧 Windows 走
125
+ `explorer.exe /select` 时也可能静默失败。现在失败会以可点击关闭的 notice
126
+ 显示在树上,不再静默吞掉。
127
+
128
+ ### 文件树文件操作(新建 / 重命名 / 删除)
129
+
130
+ - Host 早已提供 `fs.mkdir` / `fs.delete`,但客户端此前完全没接——右键菜单里
131
+ 根本没有这些项,只能看不能管。本轮接上并补齐 UI:
132
+ - 目录右键:新建文件 / 新建文件夹;文件右键:重命名 / 删除(删除为危险项,
133
+ 带名称确认)。
134
+ - 取消 prompt 或留空名是 no-op,不会误创建 `dir/`;重命名同名也是 no-op。
135
+ - 所有失败(权限 / 越界 / 占用)走同一条可见 notice,不静默。
136
+ - `fs.rename` 用「读字节 → 写入新路径 → 删源」实现,复用已有路由承载的
137
+ workspace fence,不为这一个功能给 Host 加新动词。
138
+
139
+ ### 其它
140
+
141
+ - 新增 `IconOfficeOutline16` 文件预览图标;OOXML 高保真预览外置为
142
+ `xrkh-better-sidebar-plugin-office`,本包保留 `office-legacy` 下载兜底。
143
+ - i18n:20 个语言字典补齐本轮全部新键(image* / office* / openExternalFailed /
144
+ newFolder / rename / delete 等)。
145
+ - 新增/更新测试:图片缩放 10 例、Office 组件 8 例、文件操作 10 例、OOXML 解析
146
+ 34 例(含真实 LibreOffice/pptx 文件验证,缺 fixture 时自动跳过)。全量测试
147
+ 未引入任何回归(基线红/绿保持一致)。
148
+
149
+ ## 0.19.5
150
+
151
+ - 修复底栏偶发空白(拖侧栏才出现):未测到中心列时 `left+right` 回退成零宽;改走 `--xrkh-center-*`,未测到前右侧回退为 workbench + Overview inset
152
+
153
+ ## 0.19.4
154
+
155
+ - 重新发布:npm 上 0.19.3 卡在 staged 未公开(E409),内容与 0.19.3 相同
156
+
157
+ ## 0.19.3
158
+
159
+ - 修复拖动 Host **概况** 时工作台 toggle 集群不跟手:跟 `details inset + workbench width` 停在主列右缘;拖拽中关闭 `right` 缓动
160
+ - 删除已无消费者的 `data-*-sidebar-collapsed` body 标记与钉死视口右上角的冗余路径
161
+
162
+ ## 0.19.2
163
+
164
+ - 重新发布:npm 上 0.19.1 卡在 staged 未公开(E409),内容与 0.19.1 相同
165
+
166
+ ## 0.19.1
167
+
168
+ - 修复内部 SIDEBAR_SERVICE_VERSION 仍报 0.18.32 的疏漏(功能与 0.19.0 相同;npm 0.19.0 包内版本串未对齐)
169
+
170
+ ## 0.19.0
171
+
172
+ - 完善右侧工作台与 Host **概况(Overview)** 共存:toggle 集群始终按 `details inset + workbench width` 停在**主对话列右缘**,不再叠在概况顶栏
173
+ - 完善展开/收起过渡:与 Host shell 共用 motion 时长与缓动;会话顶栏为 toggle 预留的 padding 跟随概况开合
174
+ - 建议搭配 **XRK-Harness ≥ 0.5.9**(LayoutInsets / 概况 inset 契约)
175
+
176
+ ## 0.18.30
177
+
178
+ (相对未落地的 0.18.29:同批修复。npm 上 0.18.29 卡在 staged 未公开,以本号为准。)
179
+
180
+ - 修复对话尾部文件行整个 slot 渲染崩溃(`Cannot read properties of undefined (reading 'modified')`)。**0.18.27 回归**:三条 lane 改造时把组件 prop 从宿主契约名 `matched` 改成了 `lanes`;ui-slots chain 始终把 selector 返回值注入为 `matched`(`ChainEntryProps`),同槽的 `@xrkseek/client-ui-deliverables` 也按 `matched` 读。改名后组件拿到 `undefined`
181
+ - 组件侧:只认 `matched`;用 `isFileLanes` 校验形状;缺失/坏形状时从宿主一并展开的 owner 字段重算 lanes,不再直接读 `.modified`
182
+ - 与宿主 Diff 卡共存:本轮已有 `workspace/changes` 卡时(按 closing `seq`,对齐宿主 `changesForClosing`)主动放弃 takeover,避免盖住 ChangedFiles;文件打开仍走 `workspaces.openPath` 拦截
183
+ - 测例钉住「select 输出 → 宿主 prop 名 `matched` → 组件消费」整条边界(此前只断言注册元数据,改错名字也会绿灯)
184
+ - 文件树:活动页心跳 1.2s→4s、隐藏 6s→12s;保存后 `nudgeTreeWatch` 立即拉一轮,少无感狂刷
185
+
186
+ ## 0.18.28
187
+
188
+ - 文件树增量自动刷新:AI 建/改/删文件后,已展开的树无感更新。Host 侧新增按 `sessionId` + 目录管理的非递归 `fs.watch` registry(per-subscriber 引用计数、单调 sequence + 有界 replay、watcher 失效自动重开),配 `fs.watch.sync`(只回「哪几层变了」+ 游标)与 `fs.tree.batch`(批量 listing + 可选 `statPaths`)
189
+ - 客户端共享 watch broker:同一会话/cwd 的文件树与多个编辑器合并成一份订阅与一轮请求;活动页 ~1.2s、隐藏页 ~6s、失败退避 4s;健康时每 20 轮全量 sweep,有不可监听目录时 5 轮
190
+ - 刷新语义:只替换真正变化的已加载层(`levelSignature` 比对,相同则跳过 setState),不显示 loading、不调 `refreshTick`、不物化未展开目录、不动展开/搜索/滚动/拖拽状态
191
+ - 打开中文件的外部修改:`mtimeMs` 贯穿 `fs.read` → 渲染 → baseline;内容 clean 时静默重载,dirty 时绝不覆盖草稿,显示「文件已被外部修改,草稿未覆盖」提示条与刷新按钮;无 baseline 的 viewer 不循环重载
192
+ - 修复:`fs.tree.batch` 的 listing/stat 回显改为调用方传入的原始路径(此前回显 Host 解析后的 realpath——symlink workspace root、Windows 大小写或分隔符规范化下,客户端的层级 key 与 stat 行会永久匹配不上,树看起来「不再刷新」)
193
+ - 点击卡顿(静态定位):`TreePanel` 加 memo 渲染边界、树回调 `useCallback` 稳定化、`FileTree` 单次 `setData` 批量提交(原为逐层提交)、CodeMirror 语言包按语言 key 缓存
194
+ - 测试环境:`vitest.config.ts` 加 `resolve.dedupe: ['react', 'react-dom']`(插件与宿主根各装一份 React,经 `client-ui-primitives` 跨界渲染时全部 UI 测试死于 `Invalid hook call`)
195
+ - i18n:19 个语言字典补齐 7 个漏键(`fileChangedOnDisk` / `laneModified` / `laneDeleted` / 四个 `viewer*`)
196
+ - 冗余清理:删除无消费者的 `onDegraded` 钩子、`mergeLevel` 导出与重复的 `messageOf`;`locales.spec.ts` 里测 0.18.0 已删除的 `attachBetterLocale` 覆盖层协议的残留一并清掉
197
+
198
+ ## 0.18.27
199
+
200
+ - 对话尾部文件行:按「本次改动 / 本次删除 / 本次产出」三条 lane 渲染(此前只有一条「本次产出」,改动与删除被丢弃)
201
+ - 修复根因:接管 `conversation.chat.turnTail` 时只挑 `path`、丢掉 Turn 数据里的 `op`,等于把内核已有的 lane 压平;删除的 chip 置灰划线、不可点(文件已不存在)
202
+ - 无 `op` 的旧会话回落:`workspace/changes` 行数启发式(0 增有删 → 删除,0 删有增 → 产出,其余 → 改动)
203
+
204
+ ## 0.18.26
205
+
206
+ - 终端:挂起唤醒后画布空白时 fit/refresh;网格仍死则 remount 并重挂 PTY;关闭 `allowTransparency` 减轻 GPU 挂起后整页空白
207
+ - Desktop:忽略塌缩的 `visualViewport` 当键盘 inset(避免布局推挤空白条与 `overflow: clip` 裁切面板)
208
+ - 偏好默认与 Host 对齐:`openByDefault` / `bottomPanelAutoTerminal` 默认关
209
+ - 布局:双写 `data-xrkh-sidebar-*` 与 `--xrkh-workbench-*`;存储键 `xrkh-sidebar:v1`(迁移旧 `dsh-sidebar:v1`)
210
+
211
+ ## 0.18.21
212
+
213
+ - `openTab({ type: 'editor' })` 固定落到侧栏分栏(`splits`),不因 `activePane` 在底栏而撑开底部面板(避免聊天开文件先出空白底栏 / 自动终端)
214
+
215
+ ## 0.18.20
216
+
217
+ - 拖拽分栏时合并 resize(一帧一次、跳过无变化),避免 Windows ConPTY 反复重打「版本」MOTD
218
+ - Host 短暂不可用(5xx / 空 1006)时软重连更久,不把已绘出的 MOTD 盖上致命横幅
219
+ - SSE 与 input/resize POST 不再共用 AbortController,关流时不误取消在途控制请求
220
+ - 载波仍同 0.18.19:页面同源 `xrk-app://app`(池隔离归 Desktop/Face,不在本插件翻)
221
+
222
+ ## 0.18.19
223
+
224
+ - Desktop 终端:SSE/POST 回到页面同源 `xrk-app://app`(去掉会 `Failed to fetch` 的 `xrk-app://stream` 分裂与回退冗余)
225
+
226
+ ## 0.18.18
227
+
228
+ - 轨图标:面板展开时贴齐 34px 页签条(`+3`),收起时仍对齐会话标题行(`+14`),不再下偏
229
+ - Desktop 终端:SSE 不再带 `Accept`;`stream` 主机打不开时曾回退 `app`(已由 0.18.19 去掉回退)
230
+
231
+ ## 0.18.17
232
+
233
+ - 右侧面板顶距改为单一 `top`(`--dsh-title-bar-strip` → `--xrk-desktop-chrome-height`),去掉 `padding-top` 叠 chrome,修复 Desktop 页签上方空带
234
+
235
+ ## 0.18.14
236
+
237
+ - `title-bar-compat`:`--dsh-title-bar-strip` 已含 Desktop chrome,不再叠加 `--xrk-desktop-chrome-height`(侧栏轨图标不再比标题栏矮一截)
238
+ - toggle cluster:与会话标题行垂直对齐(`+14px` · `align-items: center`)
239
+ - 启动期 panel/FAB 隐藏:去掉插件侧重复 CSS,统一由内核 `data-xrk-booting` 负责
240
+
241
+ ## 0.18.12
242
+
243
+ - 启动 splash(`data-xrk-booting`):隐藏 panel-host / FAB,避免与 HARNESS 启动页叠层
244
+ - 会话头「Session log」:有 toggle cluster 时始终右缩,展开动画中不再被按钮挡住
245
+ - 动效:主题 token 冷启动回退 380ms / cubic-bezier,展开收起不再僵硬跳切
246
+ - Desktop chrome:右侧面板与 FAB 避开 `--xrk-desktop-chrome-height`
247
+
248
+ ## 0.18.11
249
+
250
+ - 文件页:`openTab({ type: 'editor' })` 聚焦已种子的 files-home,不再并排冒出第二个「文件」标签
251
+ - `applyDedupe`:`dedupeKey` 返回 `undefined` 时仍按同 cohort 去重(与 pathless 编辑器一致)
252
+ - 底栏首次展开:若已有 UI 终端则跳过自动再开一个
253
+
254
+ ## 0.18.10
255
+
256
+ - Desktop(`xrk-app://`):终端改走 Host HTTP SSE + POST(`/sidebar/api/pty/*`),不再对无 listen 的私有 Host 死循环 WebSocket 重连
257
+ - 无边框窗口:右侧面板留 2px 边缘,便于 Electron 命中缩放
258
+
259
+ ## 0.18.9
260
+
261
+ - `openTab`:当前会话下任意打开(含仅 `type` 的 Files / +菜单)都会展开已折叠侧栏,调用方无需再自行 `togglePanel`
262
+
263
+ ## 0.18.3
264
+
265
+ - Client fiber 注入 `layout`(与 `ui-sidebar` 同序):等 `ui-layout` 声明中心栏后再挂侧栏拦截,避免 Host ≥0.3.4 上 `conversation` slot 竞态
266
+ - `xrk.client.inject` 补 `@xrkseek/client-ui-layout`;文档 Host 基线改为 **≥ 0.3.4**
267
+
268
+ ## 0.18.2
269
+
270
+ - Files 主页签随 locale;轻量媒体预览;默认打开侧栏
271
+
272
+ ## 0.18.1
273
+
274
+ - `subagents.live`:兼容嵌套 `tool` 与旧版扁平 `tool` wire,避免子代理活动预览崩溃
275
+ - 与 Host 原生 `/sidebar/*`(嵌套 live 形状)对齐
276
+
277
+ ## 0.18.0
278
+
279
+ - XRKH 原生:去掉第三方双轨(旧 manifest · better-locale · 旧安装脚本 · 市场目录)
280
+ - peer 仅 `@xrkseek/*` + React;工具类型走 `@xrkseek/xrk-tools` / `xrk-settings`
281
+ - 无 Side Chat;子代理走 Host Face + `subagents.live` / `jobs.*`
282
+ - 空 curated 插件目录(社区扩展不随包捆绑)
283
+
284
+ ## 契约
285
+
286
+ | 项 | 说明 |
287
+ |----|------|
288
+ | npm | `xrkh-better-sidebar` |
289
+ | 仓库 | `xrkseek/xrkh-better-sidebar` |
290
+ | 形态 | **仅 client 半包**(`package.json` → `xrk.client` → `lib/client.js`) |
291
+ | 注入 | `client-runtime` · `client-locale` · `client-ui-slots` · `client-ui-layout` · `client-ui-conversation` · `client-modules` |
292
+ | Host | **产品 Host 拥有** `/sidebar/api` · `/sidebar/file|upload|html|bundle` · `/sidebar/ws/terminal` 等;本包不在 XRK 上挂 Cordis host 半包抢同一前缀 |
293
+ | 子代理 / 任务 | 走 Host Face + `/sidebar/api` 的 `subagents.live` · `jobs.*`(勿再实现 Side Chat) |
294
+
295
+ 契约细则见 Harness 教科书 [community-plugins.md](https://github.com/xrkseek/XRK-harness/blob/main/docs/community-plugins.md)「侧栏插件契约」。
296
+
297
+ ## 开发
298
+
299
+ ```bash
300
+ pnpm install
301
+ pnpm bundle
302
+ ```