Главная Обзор Помощь
Регистрация Вход
haiany
/
deepseek-harness
зеркало из https://github.com/deepseek-ai/deepseek-harness.git
1
0
Ответвить 0
Файлы Задачи 0 Вики
Ветка: master
Ветки Метки
deepseek-harnes...
/
packages
/
client
/
ui-sidebar-documentpreview
/
README.zh.md

README.zh.md 17 KB
Постоянная ссылка История Исходник

description: "右侧 Sidebar 的文档预览：共享文件加载与控件，可选 Markdown、代码、图片、PDF、Office 和 HTML 渲染器，并以纯文本兜底。"

kind: "package-reference"

@deepseek-ai/dsh-client-ui-sidebar-documentpreview

English | 中文

概述

在右侧 Sidebar 预览可读文件，无需另开 tab 即可切换已注册的渲染器。Markdown 和代码接收累计文本页；PDF、HTML 和常见图片接收完整字节；未知文件扩展名使用纯文本。Office 文档在本地转换为 PDF。tab 负责加载、文件状态、渲染器选择、换行和重新载入，文档正文通过同一元数据注册表与子 slot 注册。Sidebar tab 的 kind 为 text。

目录

注册了什么

  • 类型 —— ctx.sidebarRightTabs.register(...)，id 为 @deepseek-ai/dsh-client-ui-sidebar-documentpreview（这个实现在 tab 系统中的身份，也是其正文注册所用的键），kind text，pattern dsh-resource://file/**，档位 fallback。canOpen 只接受 Session 地址，其中路径可为相对或绝对路径；不认领裸 absolute 地址。在 extension 或 builtin 档以更窄 pattern（比如 *.png）注册的类型接走那些地址；其他受支持文件落到这里。整个地址就是内容身份，所以不同目录下同名的两个文件、或同一路径在两个会话之下，是两个 tab；解码后的 basename 是 tab 标题，keyed slot sidebar.right.pane.tab.title 会在标题前放置按扩展名选择的 FileTypeIcon。
  • 正文 —— keyed slot sidebar.right.pane.tab，键为类型的 id。固定头部在可用时显示 Host 的绝对路径，否则显示请求路径；目录使用三级标签色，文件名使用一级标签色，路径过长时保留末段并向开头淡出，提示中仍提供完整值。有多个受支持的渲染器时才显示下拉菜单。仅文本兼容的源文件提供纯文本选项；只有一个渲染器时不显示查看器控件。已知的二进制容器后缀没有注册渲染器时，在路径头部下方显示文件类型图标和不支持预览的说明，并且不会发起读取。仅当所选渲染器声明 wrap: true 时显示换行开关；图标表示点击后切换到的模式，该偏好按 tab 保存，初始开启。重新载入仍在此头部，不放入 Sidebar 的 tab 条。正文贴合格的每条边，各渲染器自行提供内容留白，并可拥有内部滚动区。这与 Files tab 右侧预留 2px 滚动条间距的布局有意不同：Preview 使用格的完整宽度，使贴边 HTML 与代码滚动区终止于格的边缘。
  • 共享加载与视图状态，会话作用域、按 tab id 分桶。store 持有累计页或完整字节、读取与观察版本、加载/失败状态、渲染器选择、滚动位置、换行和已响应的导航 revision。普通 inject face 调用 Remote 读取，并经声明的 store action 写入。重新载入和加载模式变化会淘汰旧请求；tab 的中止信号清理其状态。

文档实现在 ctx.documentPreviews.register({ id, extensions, binaryExtensions?, priority, title, loading, wrap? }) 注册元数据，并以相同 id 向 keyed、Session 作用域的子 slot sidebar.right.tab.document 注册正文。binaryExtensions 列出 extensions 中不可按文本阅读的后缀，这些后缀不提供纯文本选项。两处注册都由 effect 持有，通过 ctx.slots.inject 等待子 slot。正文接收 resourceAddress、content、wrap、scrollportRef 和标准 useTabInfo/useResource 钩子。内部滚动元素挂载 scrollportRef；卸载时恢复共享正文的滚动职责。注册表保留所有匹配备选：extension（默认）优先于 builtin，随后按更长的后缀、再按注册顺序排列。所选实现仍可用时，下拉选择保持不变。HTML、SVG 和未匹配的扩展名保留纯文本回退，与加载方式无关。

loading: 'text-pages' 和 'bytes-complete' 使用共享文件读取器。选择 'renderer' 时，所选正文在读取任何字节前挂载，并接收 content: { kind: 'renderer', revision, loaded, reload }。其注入回调负责内容加载、错误和取消。loaded(version) 为共享变更提示报告已展示的源版本；已被替换的 revision 所发出的报告会被忽略。reload() 增加 revision，正文据此取消并替换当前请求。正文也在卸载和 tab 关闭时取消请求，将已完成内容保留在自己声明的 tab store 中，并在 tab 结束时释放。Office 预览 使用此模式，转换后的字节和字体元数据不会进入共享文件 store。

地址

tab 使用 fileAddressFor 构造的 Session 地址，携带相对或绝对路径。hostFileOf(address) 仅从地址取得 Session，不接收外部 Session 参数，也不借用当前或 Tab Session。Host 通过 Session 文件系统解析文件及关联路径，由该后端控制读取权限。任何 UI（包括 Global 组件）都共享同一完整地址的元数据。Workspace Files README 定义这些规则；渲染器选择不改变导航地址。

怎么读

正文通过 useTabInfo().tab 读取记录、导航和生命周期。useResource<'file'>(tab.contentId) 提供元数据，普通 inject 回调提供内容读取：

  • 资源快照仅包含 status、value 和 failure；value 是 WorkspaceFileStat 元数据。提供方可用后，内容读取无需等待首个元数据帧。观察失败优先于 Preview 的变更提示显示；两者都不会自动替换已加载内容。
  • 文本页 —— 纯文本、Markdown 和代码通过 inject 回调调用 remote.workspaceFiles.read(sessionId, path, { offset }, signal)。首次挂载读取第一页；滚动到正文末尾或点击 加载更多 会读取下一页，直到 eof。owner 以 { kind: 'text', text, pages, eof } 提供累计前缀，包含源码偏移和行数。Markdown 和代码增量渲染此前缀，不把每页当成独立文档。第一页之后到达的更新版本页会使读取从头开始，避免混合版本。尚无内容时，失败会以文件类型图标、说明与重试按钮填满正文；较晚的失败保留已有内容并在其下提供重试。
  • 完整字节 —— PDF、HTML 和常见图片通过 inject 回调调用 remote.workspaceFiles.readAll(sessionId, path, signal)。rpc.ts 将线路上的 base64 解码为 data: Uint8Array<ArrayBuffer>，供 { kind: 'bytes', data } 使用。Host 的 maxFileBytes 上限拒绝超大文件，不截断。PDF 在传给 worker 前复制保留的字节，使 Preview 缓冲区仍可使用。字节仅保存在临时视图状态中，绝不进入持久布局或 Session JSONL。加载模式变化会淘汰先前结果。
  • 重新载入 —— 仅当前 Preview tab 通过自己的 Remote 回调重读，保留滚动偏好并淘汰旧请求。变更提示将读取版本及起读时的观察版本与后续 resource.value.version 比较；刷新前已观察到的版本不会被当成新变化。读取既不刷新共享元数据，也不清除其它 tab 的提示。

HTML 以贴合正文四边的 Blob iframe 运行，沙箱属性严格为 sandbox="allow-scripts"，不含 allow-same-origin；脚本无法访问父应用的源或文件读取接口。渲染器通过普通 inject 回调调用 remote.workspaceFiles.readRelated，加载直接声明的相对 .js 经典脚本和 .css 样式表；固定安全上限为单个资源 4 MiB、总计 32 MiB、64 个不同资源。Host 代码解析关联路径，rpc.ts 解码返回的字节。在渲染器内部，base64 仅用于把 iframe 引导载荷嵌入脚本文本。<base href> 将依赖解析交给浏览器，HTTPS 资源也由浏览器处理。本地模块 import、CSS url()/@import 和动态 fetch 不使用 Host 文件访问。读取失败、无效 UTF-8 或超出上限都使预览失败，不发布部分资源包。替换或卸载文档会释放其 Blob URL。

PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 <img> 静态图片上下文中渲染，带 12px 内边距和圆角。宽图按固有纵横比缩小到面板宽度，小图按固有 CSS 像素尺寸居中，超高图纵向滚动。渲染器既不提供缩放，也不提供拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此其中的脚本无法执行，也无法访问父页面。替换或卸载图片会撤销其 Blob URL。

共享文案来自 sidebarDocumentPreview；各内置渲染器拥有自己的本地化标签。PDF 与转换后的 Office 预览在浅色模式下使用石墨灰底色，在深色模式下使用哑黑底色，页面带有轻微阴影并保留文档原色。

首次读取、追加页及 HTML/PDF/图片准备共用仅图标的加载 spinner，其标签暴露给辅助技术，并遵循减少动态效果偏好；内容出现前的每个等待都把 spinner 居中在面板中，打开文件到正文出现始终是同一位置的一个 spinner。下一页加载期间保留已显示的内容。PDF 正文仅在 PDF 预览挂载时加载包内 client.pdf.js chunk；PDF.js、Worker 源码和内嵌支持数据不会进入启动 client.js。PDF 页面贴边占满面板宽度，组成一个纵向连续序列并在接近视口时惰性渲染；未渲染的页以安静的 3:4 占位块保持位置。PDF.js 官方 TextLayerBuilder 在与画面重合的文字层上管理选区边界和复制文本规范化。配套样式不高亮空白换行；对齐同时考虑 PDF 页面单位、页面旋转与视口宽度变化，页面释放时取消两层渲染。纯图片 PDF 不包含可选取的文字。代码预览默认显示源码行号，但复制文本不包含行号；纯文本与代码使用相同字号和行高。代码直接坐在分栏自身的背景上，而不是会话卡片的填充色；复制条与占满剩余高度的内部滚动区相邻，因此横纵滚动条都从复制控件下方开始。

Office 预览

将 .doc、.docx、.xls、.xlsx、.ppt 和 .pptx 打开为 PDF 预览，使用与 PDF 文件相同的加载状态、控件、取消和文本选择能力。Host 提供方负责本地转换；无效文件、转换失败和超时会显示本地化消息。缺少 Host 服务时显示配置引导。

Web bundle 以 ui-sidebar-documentpreview 挂载本包。通过该条目的 office 设置配置临时 Office 缓存；配置目录定义可接受的值。设置注入到每个页面；修改 YAML 后重新加载浏览器页面。

字段 默认值 含义
office.maxCachedEntries 8 最多保留的已完成 PDF 数量
office.maxCachedBytes 67108864（64 MiB） 最多保留的二进制 PDF 字节数，按缓冲区 byteLength 计算
office.maxPending / office.maxReaders 8 / 32 未完成转换 RPC 数量 / 含元数据查询的读取方数量

打开 Office 文件时按需请求转换。每次读取都先检查渲染 generation 和已授权的源文件元数据，再共享进行中的转换或复用成功的 PDF。缓存以渲染 generation、Session、源文件绝对路径和源版本作为身份；通过淘汰最久未使用的 PDF，使保留量符合两项限制。失败和超过字节限制的 PDF 不会被保留。转换后 PDF 的返回渲染 generation 与缓存身份一致时，才会保留该 PDF。取消一个读取方后，共享转换会继续运行，直到最后一个读取方离开。连接重置会清空缓存字节并取消待完成读取；插件卸载还会等待未结束的请求完成。PDF 从不持久化；传输字符串、解码存储和 PDF.js 渲染内存不计入缓存限制。

后台请求为前台工作保留最后一个在途请求槽和读者槽；将任一限额设为一会拒绝后台读取。渲染器替换后会重新执行一次代次查询与授权检查。重试期间再次替换会显示本地化的繁忙提示。

黄色提示条说明转换时不可用的字体。“显示更多”打开锚定字体列表；关闭列表保留提示条。关闭提示条会收起其占位并使 PDF 上移，关闭状态仅在预览持续挂载且源文件版本相同时保留；切换到其他标签再切回会重新显示提示条。过长提示文字在操作按钮前渐隐，减少动态效果偏好会禁用收起动画。

Office 实现——点击展开 Office 注册、加载、缓存和字体提示位于 `src/client/office/`。Office 正文持有转换后的 PDF 字节和字体元数据，并声明嵌套 PDF slot，复用惰性 PDF 正文及其 tab 阅读状态。字体提示位于 Office 滚动区上方。Host 渲染器缺失时，注册仍然可用；可选的 `remote.officeToPdf` 和 `remote.workspaceFiles` 注入提供转换与版本检查回调，移除后恢复不可用提示。注册和 tab 状态保留都遵循 effect 生命周期。[转换服务](../../document/office-to-pdf/README.zh.md)拥有 Host Remote 方法，由 `api/remotes` 挂载。 共享 `documentFileBytes()` 辅助函数将普通文件与转换后 PDF 的响应解码到一个独立持有的字节缓冲区，不会将字节展开为 JavaScript 数组元素。渲染器以只读方式借用保留的字节，并在传给 Worker 前复制。

导航

ctx.sidebarRight.openResource(address, { params: { line } }) 通过 file 参数携带 1 起算的源码行号。在 text-pages 模式下，owner 顺序加载到该行或 EOF。纯文本与代码渲染器提供源码行锚点；Markdown 不提供。所选渲染器没有锚点时，导航保持待处理；用户切换到纯文本或代码后执行。代码导航直接滚动内部源码视口。字节模式渲染器不消费源码行导航。每个完成的导航 revision 只响应一次。不带 revealIfOpened: false 打开同一文件时聚焦已有 tab，并送达新 revision。

模型体验

无，因为预览是纯浏览器侧的查看器，不注册工具、提示词段或会话事件。

KV Cache 影响

无直接影响；用户在这里读到的东西永不进入模型请求。

已知限制与延期工作

  • 预览而非编辑。 查看器不提供文件编辑或共享搜索接口；目录地址以 not-regular-file 失败。未知扩展名使用纯文本读取，仍受其 UTF-8/NUL 检查限制。
  • Office 转换限制。 预览不启动原生 Office 编辑器，也不下载引擎。二进制 .doc、.xls 和 .ppt 文件不返回缺失字体诊断。转换保真度与资源限制由 LibreOffice 提供方负责。
  • 文本顺序分页，完整文件受限。 定位到较深处的源码行需要先加载此前各页；PDF、HTML 和图片必须取得 Host maxFileBytes 上限内的完整结果。
  • 字节视图不恢复滚动位置。 PDF、HTML 与图片的渲染器重新挂载或重新载入时可能回到顶部；图片适配面板宽度、不产生横向滚动，HTML iframe 的滚动属于其不透明浏览上下文。
  • 本地 HTML 依赖集合有限。 只打包直接引用的经典 .js 脚本和 .css 样式表。浏览器解析的资源仍受浏览器源与网络规则限制；iframe 不获得运行时文件读取桥接。
  • 换行图标为包内自绘。 IconWrapFill16 与 IconNowrapFill16 住在 src/client/icons.tsx，直到共享图标集提供为止；它们的 props 已与共享图标契约一致。
  • 滚动写入未节流。 每次滚动事件都把偏移记进 store；行块已 memo 化，于是由此引发的重渲染交还给 React 的是同一批元素。
  • PDF chunk 加载失败后需要刷新页面。 React 会在页面生命周期内缓存被拒绝的 lazy import；已加载正文中的普通 PDF 打开或渲染失败仍可重试。

开发备注

维护者工作上下文——点击展开 无。

运行时不变式： 不发布伴生入口。渲染器元数据、文档加载和视图状态归本地注册表与声明的 Slot store 所有，没有可比对的独立运行时来源；注册释放和 tab 生命周期由行为测试覆盖。