前言¶

DeepSeek Harness (DSH) 的核心理念是“一切皆插件”。在智能体开发场景中，文件编辑能力是刚需，但现有的静态预览插件往往无法满足用户对实时协作和深度修改的需求。dsh-sidebar-onlyoffice 旨在解决这个问题，它将完整的 ONLYOFFICE 文档编辑器嵌入到 DSH 的侧边栏中，允许用户直接在浏览器内编辑 .docx、.xlsx 和 .pptx 文件。

是什么¶

dsh-sidebar-onlyoffice 是一个 DSH web 插件，由维护者 chendefine 开发。它通过自托管的 ONLYOFFICE Document Server，将真实的办公编辑环境引入到 dsh-better-sidebar 中。该插件解决了传统预览无法写入文件、网络通信受限以及与 AI 交互时编辑器状态不同步的问题。

核心功能¶

该插件包含以下核心能力：

1. 真实办公编辑
   在 better-sidebar 中嵌入完整的 ONLYOFFICE 编辑器（文档、表格、演示文稿），而非静态预览。编辑后的内容会原子化地保存回磁盘文件。

2. 同源代理
   为了解决浏览器跨域访问 Document Server 的问题，插件内置了同源代理（/sidebar/onlyoffice/ds）。整个 Document Server 的浏览器 UI（api.js、editor iframe、静态资源、Socket.IO）均通过此代理路由，使得 DSH 进程可以驻留在私有网络，而浏览器无需直接访问 Document Server。

3. 安全配置
   默认支持对编辑器配置进行 HS256-JWT 签名，并对文件下载进行短期 HMAC 令牌校验。所有浏览器可访问的路由均位于信任围栏之后，拒绝访问会话工作目录之外的文件。

4. AI 编辑实时刷新
   当 AI 修改了正在编辑器中打开的文件时，插件无需刷新整个页面或重新加载 api.js，即可通过 refreshFile 接口在约一秒内将新版本推送到编辑器。为了防止数据丢失，编辑器处于脏状态时不会自动刷新，而是提示用户手动确认。

5. 原子保存与抑制自保存
   Document Server 的回调下载字节后，通过“临时文件+重命名”的方式实现原子性替换文件。同时，插件服务器端会抑制自身的写入信号，防止用户保存操作导致光标重置或刷新回退。

6. 网络内通信
   插件使用容器到容器的内部网络通信（In-network save fetch）替代通过公共代理的“回环”请求，提高了保存操作的稳定性。

7. 插件共存
   插件 viewer id 为 onlyoffice:docx|xlsx|pptx（优先级 10），与 @huanlin/dsh-plugin-better-sidebar-plugin-office 的 docx/xlsx/pptx（优先级 0）互不冲突，用户可在侧边栏设置中按需禁用。

安装与启用¶

安装插件需要使用 DSH 的 web profile。确保环境已安装 dsh-better-sidebar 且 Node.js 版本大于等于 20。

dsh plugin --profile web add dsh-sidebar-onlyoffice

安装完成后，需要重启 dsh web 进程，并在浏览器端进行硬刷新（Ctrl+Shift+R）以加载新插件。

配置¶

插件的配置项写在 profiles/web/cordis.patch.yml 文件中。以下是关键配置项说明：

- id: dsh-sidebar-onlyoffice
  config:
    jwtSecret: "<the DS JWT_SECRET>"          # JWT 签名密钥，必须与 DS 的 JWT_SECRET 一致
    documentServerUrl: http://onlyoffice-documentserver  # DS 的网络访问地址（容器可直连）
    internalBaseUrl: http://172.31.255.4:3080    # DS 回连 DS Web 的内部地址（留空则自动检测）

注意：jwtSecret 仅在 ONLYOFFICE 启用 JWT 时需要。

注意事项¶

1. 环境依赖
   需要运行 DSH web profile，且已安装 dsh-better-sidebar。必须部署自托管的 ONLYOFFICE Document Server（已验证兼容 9.4 社区版）。

2. 网络与权限
   如果 document.url 或 callbackUrl 使用私有地址，DS 需要设置环境变量 ALLOW_PRIVATE_IP_ADDRESS=true 才能接受请求。

3. 安全与维护
   安装前建议查阅源码以确认安全性逻辑。由于插件以当前 DSH 进程的权限运行，请确保 Document Server 的配置符合当前网络拓扑的安全要求。

结语¶

dsh-sidebar-onlyoffice 为 DSH 提供了从“只读预览”到“实时编辑”的完整闭环。通过 JWT 安全机制、同源代理以及精细的 AI 交互控制，它使得在智能体工作流中直接操作办公文档成为可能。更多细节可参考插件目录或源码仓库。