人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载导读本文以 ClawX 仓库中的 office-document-preview 任务规格 与 Office Document Preview 参考文档 为主体深入讲解 ClawX 如何在已授权的文件预览表面Chat 会话、附件、工作区浏览器中实现 DOCX/PPTX 只读内联预览包括格式与大小限制契约、Renderer 端懒加载与解析边界、三类授权二进制读取路由、DOCX 的 Shadow Root 隔离渲染、PPTX 的串行调度与单实例约束以及 Chat 预览区的全屏覆盖层。读完本文你将掌握 ClawX 文件预览系统的完整安全模型、核心实现文件与验证测试并可直接在仓库中按图索骥查阅每一处机制。背景与范围ClawX 是一款为 OpenClaw AI Agent 提供图形界面的桌面应用。其文件预览功能覆盖文本、Markdown、图片、PDF、表格、HTML、源码与 ACP Changes 等多种格式。本任务在此基础之上为已授权的文件表面新增了 Office 文档DOCX/PPTX的只读内联预览并提供一个填满 Renderer 视口的 Chat 预览全屏模式。任务的完整契约记录在 harness/reference/office-document-preview.md安全与生命周期要求由 harness/specs/rules/office-preview-safety.md 强制约束二者共同构成 任务规格 的落地依据。本实现属于chat-workspace-and-navigation场景的扩展不新增任何通信传输通道也不引入 Main 进程文档转换路径——所有 Office 字节只在 Renderer 内解析。格式与大小限制契约扩展名权威Extension-Authoritative判定Office 内联预览采用扩展名权威策略只有以下 OOXML 扩展名会进入 Office 解析器且当 MIME 与扩展名冲突时以扩展名为准扩展名MIME 映射预览类型解析器压缩输入上限.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentdocxdocx-preview20 MB20 * 1024 * 1024字节.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentationpptxpptxviewjs1.1.920 MB20 * 1024 * 1024字节MIME 单独永远不会把未知、缺失、.doc或.ppt扩展名送入 OOXML 解析器传统.doc/.ppt保持“仅系统打开”行为。Office 预览只读不暴露 Source 或 Diff 标签页。这一判定逻辑可在 src/lib/file-preview-capabilities.ts 中看到完整实现richFilePreviewKind()依次检查isSystemOpenOnlyExtension其中SYSTEM_OPEN_ONLY_EXTENSIONS显式包含.doc、.ppt、isDocxPreviewExt、isPptxPreviewExt最后才回退到 MIME 判断从而保证扩展名优先级。精确的大小限制契约预览大小限制使用共享的判别式discriminated契约实现在 shared/file-preview/limits.ts预览目标最大接受输入文本2 MB2 * 1024 * 1024字节DOCX 或 PPTX 富预览20 MB20 * 1024 * 1024字节图片、PDF 或表格富预览50 MB50 * 1024 * 1024字节限制语义精确到字节最大值本身被接受超过一个字节即被拒绝。Office 限制作用于解析前的压缩输入。已知超限的文件不会挂载 viewer、也不会导入解析器未知大小文件以 Office 限制作为 Host API 读取的maxBytes因此即使读取期间文件增长也会返回tooLarge而不会把解析器输入传入。该边界由 src/lib/file-preview-capabilities.ts 的filePreviewMaxBytes()与isFilePreviewWithinSizeLimit()强制执行attachmentOpenMode()则据此为附件选择preview或system打开模式。依赖与加载策略Office 预览涉及四个依赖版本以 package.json 为准docx-preview^0.4.0将 DOCX 字节转换为用于分页预览的 HTML 与 CSS。其不完整的 Word 排版模型是已接受的效果保真度限制。pptxviewjs1.1.9精确锁定解析 PPTX 包并逐页绘制到 Canvas。版本被钉死是因为评审通过的全局状态、调度器、清理与保留策略均针对 1.1.9 设计。jszip^3.10.1满足 PPTX 解析器的 peer 依赖也是所选 Office 解析依赖使用的 ZIP 实现。chart.js^4.5.1提供chart.js/auto被所选pptxviewjsESM 构建导入用于绘制受支持的嵌入图表。关键加载策略FilePreviewBody与WorkspaceBrowserBody通过 Reactlazy()加载两个 Office viewer 组件每个 viewer 仅在授权且未超限的二进制读取成功之后才动态import()各自的解析器。以 src/components/file-preview/DocxViewer.tsx 为例读取成功后才执行const { renderAsync } await import(docx-preview)src/components/file-preview/PptxViewer.tsx 同样在读取成功后await import(pptxviewjs)。这样可确保 viewer、jszip、chart.js与解析器代码不进入同步的 Chat 入口路径且被拒绝的输入永远不会触发解析器初始化。读取权威Read Authority每个 viewer 恰好选择一条已存在的二进制路由并统一传入 20 MB 上限见 src/lib/file-preview-client.ts 的readBinaryFile/readWorkspaceBinary/readAttachmentBinary目标权威读取路由普通本地路径含 Workspace Browser 已校验的绝对路径readBinaryFile(filePath, { maxBytes })显式WorkspaceFileRefreadWorkspaceBinary({ ...workspaceFileRef, maxBytes })显式AttachmentFileRefreadAttachmentBinary(attachmentFileRef, maxBytes)安全约束同时包含两种 scoped 引用类型的目标是无效的在任何读取之前即失败DocxViewer.tsx 中attachmentFileRef workspaceFileRef直接进入error状态scoped 目标永远不会通过filePath、其他作用域或裸路径 API 重试。Workspace Browser 刻意保留其 Host 校验过的绝对路径路由其他工作区派生的文件活动则以WorkspaceFileRef进入预览。远程附件不进入预览也不存在为预览而生的下载流程。文档字节始终停留在现有 Renderer/Main Host API 边界内Renderer 向解析器 API 传递Uint8Array不使用直接文件系统访问、文档fetch()、解析器 URL 加载器、临时文件、上传、Gateway 端点也没有 Main 进程或外部转换服务。超限行为的权威路由超限行为跟随目标权威而非显示表面目标行为普通本地 Preview 目标展示 too-large/直接打开表面带确认后的系统打开与在文件管理器中显示操作Workspace Browser 校验过的绝对路径展示同样的确认后直接打开与显示操作已知超限的本地授权附件attachmentOpenMode()选择现有 scopedhostApi.files.openAttachment()系统打开流程远程附件保持现有 scoped 系统打开流程不为预览下载WorkspaceFileRef预览目标展示tooLarge无裸路径 shell 操作有界读取检测到竞争期大小增长的 scoped 附件展示tooLarge不回退到裸路径这一区分的根本原因普通路径拥有本地 shell 权威而 scoped 引用只保留其 scoped Host API 权威。实现上src/components/file-preview/FilePreviewBody.tsx 的allowSystemActions !file.attachmentFileRef !file.workspaceFileRef是这一权威划分的直接体现而“直接打开”走 src/components/file-preview/open-file-utils.ts 的confirmAndOpenFile()确认对话框后调用hostApi.shell.openPath与revealFile()hostApi.shell.showItemInFolder。DOCX 渲染Shadow Root 隔离与页面缩放DocxViewer为每次目标生成创建新的分离detachedbody 容器与样式容器在两者均未挂载时调用renderAsync()待当前代generation的容器渲染完成后才追加到 React 宿主元素上打开的 Shadow Root 中src/components/file-preview/DocxViewer.tsx 中DOCX_SURFACE_CSS、shadowRoot.append(styleContainer, surfaceStyle, bodyContainer)。因此生成的文档 CSS 与 DOM无法改写 ClawX 布局过期的读取或渲染也无法替换当前选中的文档。渲染选项是精确约定的源码中DOCX_RENDER_OPTIONS与文档完全一致{ className: clawx-docx, inWrapper: true, ignoreWidth: false, ignoreHeight: false, ignoreFonts: false, breakPages: true, ignoreLastRenderedPageBreak: false, renderHeaders: true, renderFooters: true, renderFootnotes: true, renderEndnotes: true, renderChanges: false, renderComments: false, renderAltChunks: false, useBase64URL: true, experimental: false, debug: false, }要点解读renderAltChunks: false阻止嵌入的 HTML 部件进入预览批注comments与修订tracked changes被禁用。useBase64URL: true避免库创建的 Blob URL 生命周期问题并让生成的资源可随 Shadow Root 容器一起释放。链接隔离在 Shadow Root 上捕获click与auxclick监听器阻止每个生成锚点的默认行为preventAnchorActivation检查composedPath()中是否含HTMLAnchorElement。Hash、HTTP(S)、file 与自定义协议链接全部不可交互——DOCX 预览无法导航 ClawX 窗口也无法调用 shell 权威。页面缩放页面保持居中、纵向、按作者尺寸排版的纸张形态。ResizeObserver先将 body CSSzoom重置为1测量最宽的section.clawx-docx再应用Math.min(1, host.clientWidth / widestPageWidth)。Chromium CSS zoom 会同步缩放尺寸与文本流viewer 只会缩小适配绝不会放大超过作者尺寸。清理目标替换或卸载时ClawX 断开 observer、移除生成的样式/body 容器、清空其子节点并释放直接的字节与 DOM 引用。不可取消的渲染可能在清理后完成但代generation校验会阻止其挂载过期内容isCurrent()检查generationRef.current generation committedIdentityRef.current loadIdentity。PPTX 渲染串行调度与单实例约束渲染与调度PptxViewer使用一个以目标身份identity为 key 的 React 托管 Canvassrc/components/file-preview/PptxViewer.tsx 中canvas key{loadIdentity} .../。与 DOCX 不同PPTX 的初始 Canvas 在pptxviewjs渲染时才挂载不要求先在分离 Canvas 上渲染。目标身份、已提交代校验与最新请求校验可防止过期工作发布React key 替换或卸载则分离废弃 Canvas。PPTXViewer构造函数只接收以下行为关键选项{ canvas, enableThumbnails: false, slideSizeMode: fit, backgroundColor: #ffffff, autoChartRerenderDelayMs: 0, }初始渲染前viewer 最多等待 60 次正数尺寸检查最多 59 次动画帧等待waitForPositiveSize实现。每次渲染前都将当前容器宽高作为 Canvas CSS 尺寸同步。slideSizeMode: fit在居中的预览表面内保持源纵横比。模块级 promise 队列串行化所有pptxviewjs操作schedulePptxOperation构造、loadFile()、幻灯片数访问、初始渲染、恢复位置渲染、导航、图表刷新、缩放渲染与destroy()。每个渲染请求携带代、请求身份、最新幻灯片与最新测量尺寸执行前已过期的任务被跳过。失败的当前渲染终止该生命周期而被拒绝的过期渲染不能替换或失败新目标。演示文稿每个挂载目标只解析一次。初始渲染总是绘制第 0 页若所属表面存有同一目标身份的位置索引则先夹取到已加载幻灯片范围再渲染。位置显示为 1 起始边界处与渲染中禁用导航onSlideIndexChange只在成功的当前渲染后触发。缩放与图表ResizeObserver采用 100 ms 尾部防抖回调不直接渲染防抖后重新读取尺寸并排队当前页刷新。autoChartRerenderDelayMs: 0禁用依赖库不可取消的延迟图表渲染全局chartRenderingComplete监听器在刷新挂起时合并事件并通过同一串行调度器提交刷新。清理时移除监听器、observer并取消所有自有 timer 与动画帧。为什么只能有一个 PPTX 实例pptxviewjs1.1.9将演示文稿的图表与 ZIP 状态存储在 Renderer 全局中包括window.currentProcessor与window.currentZipData。因此共享 Electron Renderer 中最多只能挂载一个PptxViewer——这是正确性要求而非性能偏好并发演示文稿可能从错误的演示中解析图表或包数据。因此 Workspace 与 Preview 表面保持挂载以保留周边 UI 状态但每个表面只在自身 artifact 标签页激活时有条件地挂载 PPTX 子组件src/components/file-preview/FilePreviewBody.tsx 中active ? PptxViewerLazy .../ : nullWorkspaceBrowserBody.tsx 同样return active ? ... : null。仅靠 CSShidden隐藏不够。开发模式下 PptxViewer.tsx 的useLayoutEffect断言hasActiveDevelopmentInstance会直接throw new Error(PptxViewer requires a single active instance)拒绝第二个并发 viewer。所属表面以目标身份为 key 的 Map 保存幻灯片位置切换离开即销毁并卸载 viewer切换回来重新解析演示文稿并恢复夹取后的位置。清理时按调度顺序为活跃实例排队一次公共destroy()destroyViewerInOrder保证恰好一次并移除全部自有引用。文档明确由于依赖库限制这不承诺其内部资源的完全回收。全屏预览表面Fullscreen PreviewChat 预览区头部暴露一个本地化的图标控件把选中的FilePreviewBody移入一个填满 Renderer 视口的 portalsrc/components/file-preview/ArtifactPanel.tsx 中isFullscreen ? createPortal(preview, document.body) : preview。要点这是应用覆盖层不是 Electron 窗口全屏且对 Preview 表面支持的所有文件格式一致生效。在紧凑面板布局与全尺寸布局之间切换时保留目标身份与目标 key 化的 PPTX 幻灯片位置pptxSlidePositionsMap。同一头部控件退出全屏Escape提供键盘退出useEffect中window.addEventListener(keydown, ...)切换到 Preview artifact 标签页之外也会关闭覆盖层订阅useArtifactPanel状态。Portal 切换可能重新挂载 viewer但旧 PPTX 生命周期在替代者激活前已被拆除从而维持单挂载 viewer 不变式。全屏层同时处理了 mac 标题栏红绿灯安全内边距MAC_TRAFFIC_LIGHT_SAFE_INSET与roledialog、aria-modal无障碍语义。生命周期状态与错误处理两个 viewer 都暴露四个生命周期状态loading授权读取、懒解析器导入、解析或初始渲染进行中。readyDOCX 页面或当前 PPTX 幻灯片与控件可见。tooLarge预检或有界 Host API 读取拒绝 20 MB 以上输入。error权威校验、读取、空输入、解析、布局尺寸或渲染失败。错误使用本地化的、按格式区分的通用消息绝不展示解析器异常、解析器错误中的路径或堆栈。损坏、畸形、加密、密码保护、空或其他不支持的 OOXML 输入都可能落入error。没有自动重试循环重新选择或重新打开目标会创建一次新加载。本地化文案覆盖英语、中文、日语、俄语四种 chat 语言包shared/i18n/locales 下的en、zh、ja、ru并使用项目设计令牌。非目标Non-Goals明确不在本任务范围内的事项传统.doc/.ppt的解析或转换。编辑、保存、批注、修订、Word 搜索或目录工具。与 Microsoft Word/PowerPoint 像素级一致的排版。由生成内容触发的 DOCX 链接打开或应用窗口导航。PPTX 缩略图、导航键盘快捷键、动画、转场、媒体播放、演示者模式或自动放映——通用 Preview 表面可以填满应用视口但不实现 PowerPoint 演示者行为或原生 Electron 全屏。为预览下载远程附件。Main 进程、服务器、云端或外部服务转换。改变现有 PDF、表格、图片、HTML、Markdown、源码或 diff 行为。被拒绝的备选方案与设计取舍规格文档记录了评审中被否决的方案及其理由可作为理解安全边界的注脚MIME 驱动的解析器选择被拒传统或未知扩展名不得进入 OOXML 解析器。Main 进程或云端转换、临时文件转换、解析器 URL 加载、Rendererfetch()被拒必须保留现有权威与数据边界。DOCX 轻 DOM 渲染与可交互生成链接被拒文档 CSS 与导航不得获得应用权威。仅 transform 的 DOCX 缩放被拒变换后的页面可能重叠后续文本流Chromium CSS zoom 随内容缩放布局尺寸。在 CSShidden下保持多个 PPTX viewer 挂载被拒共享依赖全局会交叉污染演示文稿。独立的初始/导航/图表/缩放渲染路径被拒不可取消操作会竞态单一串行调度器拥有所有依赖操作与渲染来源。库的延迟图表重渲染被拒改为自有合并事件刷新同时否决了修补pptxviewjs内部评审过的公共 API 与已接受限制保持显式。已接受的风险与限制两个 ZIP 解析器都在 Renderer 运行复杂但未超限的文件可能短暂占用 UI 线程。20 MB 压缩上限降低但不能消除 ZIP 解压膨胀或高峰内存风险。docx-preview不是 Word 的分页引擎换行、分页、字体与布局可能不同。pptxviewjs对罕见形状、字体、动画、转场与媒体的 PowerPoint 保真度不完整。嵌入字体依赖平台可用字体与回退。pptxviewjs1.1.9的公共destroy()不能完全清除内部缓存、URL、延迟工作或图表相关全局反复切换演示文稿可能保留依赖库持有的内存直至 Renderer 退出。单实例规则防止并发跨演示文稿损坏但不能消除这一已接受的保留风险。未来加固方向当前 20 MB 检查是产品级性能护栏并非完整的恶意 ZIP 边界。未来 ZIP 加固可能增加解析前条目数、解压比率与 XML 复杂度预算。此类检查必须保持同样的目标权威路由并在任一解析器收到字节前失败它们未在当前版本中实现也不应被推断为已具备。验证锚点Validation Anchors规格文档为每一层实现都指定了可验证的锚点文件格式分类与限制shared/file-preview/limits.ts、src/lib/generated-files.ts、src/lib/file-preview-capabilities.ts由 generated-files.test.ts 与 open-file-utils.test.ts 覆盖。Renderer 权威、DOCX 隔离/选项/链接/缩放、PPTX 构造/尺寸/调度/图表/恢复/清理、过期代处理与通用错误DocxViewer.tsx、PptxViewer.tsx由 office-file-viewers.test.tsx 覆盖。表面预检、权威特定回退、条件挂载与位置归属FilePreviewBody.tsx、WorkspaceBrowserBody.tsx、ArtifactPanel.tsx、AcpTurnFileActivity.tsx、AcpAttachmentPart.tsx由 file-preview-body.test.tsx、workspace-browser-body.test.tsx、artifact-panel.test.tsx、acp-chat-components.test.tsx 覆盖。端到端层面office-document-preview.spec.ts 使用真实、确定性的 DOCX/PPTX 包sample.docx、slides-a.pptx、slides-b.pptx锚定 Shadow Root 页面渲染、Canvas 像素、图表完成、幻灯片导航、按目标的位置恢复、约束面板缩放、填满视口的 Preview 切换、单挂载 viewer 不变式、Host API 读取路由以及不存在传统直接 IPC。配合 chat-acp-attachments.spec.ts 与 chat-file-changes.spec.ts构成完整的行为验证闭环。全部单元与 E2E 验证可通过任务规格中列出的 Vitest、typecheck、lint、Vite build、Playwright 与 harness 命令执行。小结ClawX 的 Office 只读预览以“扩展名权威 精确字节限制 单一授权读取路由 Renderer 内解析 懒加载 代校验 单 PPTX 实例”为核心设计在既有文件预览体系上安全地扩展了 DOCX/PPTX 能力。其安全模型的核心在于普通路径持有本地 shell 权威scoped 引用只持有 scoped Host API 权威Office 内容既不能导航应用窗口也不能获得 shell 能力。理解这套契约可帮助你安全地复用、扩展或验证 ClawX 的文件预览能力。赞分享人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载相关推荐ClawX 内置 Office 文档预览深度解析DOCX/PPTX 渲染契约、20MB 大小限制与安全边界ClawX 内置 Office 文档预览深度解析DOCX/PPTX 渲染契约、20MB 大小限制与安全边界 本篇技术指南围绕 ClawX 桌面端内置的 Off人工智能AI 应用桌面应用交互助手ClawX Office 文档安全预览机制解析DOCX/PPTX 内联预览的权限边界、大小契约与渲染生命周期ClawX Office 文档安全预览机制解析DOCX/PPTX 内联预览的权限边界、大小契约与渲染生命周期 本篇技术指南以 ClawX 仓库的 AI 编码规人工智能AI 应用桌面应用交互助手深度解析vue-office如何借助docx-preview、pdfjs和exceljs实现完美文档预览深度解析vue office如何借助docx preview、pdfjs和exceljs实现完美文档预览 在当今数字化办公时代文档在线预览已成为企业应用不可示例工程上一篇如何在Firefox浏览器中一键下载Sketchfab的3D模型3步轻松获取完整资源下一篇CANN ops-cv 仓库目录结构全解析算子工程、示例与测试的组织方式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考