Introduction¶

The core philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” In agent development scenarios, file editing is an essential requirement, but existing static preview plugins often fail to meet user needs for real-time collaboration and deep editing. dsh-sidebar-onlyoffice is designed to solve this problem. It embeds a full-featured ONLYOFFICE document editor into the DSH sidebar, allowing users to directly edit .docx, .xlsx, and .pptx files inside the browser.

What It Is¶

dsh-sidebar-onlyoffice is a DSH web plugin developed by maintainer chendefine. By using a self-hosted ONLYOFFICE Document Server, it brings a real office editing environment into dsh-better-sidebar. This plugin addresses issues where traditional previews cannot write to files, where network communication is restricted, and where the editor state becomes out of sync during interactions with AI.

Core Features¶

The plugin includes the following core capabilities:

1. Real Office Editing
   It embeds a full ONLYOFFICE editor (documents, spreadsheets, and presentations) in better-sidebar instead of a static preview. Edited content is atomically saved back to the disk file.

2. Same-Origin Proxy
   To address browser cross-origin access issues to the Document Server, the plugin includes a built-in same-origin proxy (/sidebar/onlyoffice/ds). The entire browser-facing interface of the Document Server (api.js, editor iframe, static assets, Socket.IO) is routed through this proxy, allowing the DSH process to reside on a private network while the browser does not need direct access to the Document Server.

3. Secure Configuration
   By default, it supports HS256-JWT signing for editor configuration and short-lived HMAC token verification for file downloads. All browser-accessible routes remain behind a trust boundary and reject access to files outside the session working directory.

4. Real-Time Refresh for AI Edits
   When AI modifies a file that is open in the editor, the plugin can push the new version to the editor via the refreshFile interface in about one second without refreshing the entire page or reloading api.js. To prevent data loss, if the editor is in a dirty state, it will not refresh automatically but instead prompt the user to manually confirm.

5. Atomic Save and Self-Save Suppression
   After the Document Server callback downloads bytes, files are atomically replaced using a “temporary file plus rename” approach. At the same time, the plugin server suppresses its own write signals to prevent user save operations from causing cursor resets or refresh rollbacks.

6. In-Network Communication
   The plugin uses container-to-container internal network communication (In-network save fetch) instead of “loopback” requests through a public proxy, improving the stability of save operations.

7. Plugin Coexistence
   The plugin viewer id is onlyoffice:docx|xlsx|pptx (priority 10), which does not conflict with docx/xlsx/pptx (priority 0) from @huanlin/dsh-plugin-better-sidebar-plugin-office. Users can disable it as needed in the sidebar settings.

Installation and Activation¶

Installing the plugin requires using the DSH web profile. Ensure that the environment already has dsh-better-sidebar installed and that the Node.js version is 20 or higher.

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

After installation, restart the dsh web process and perform a hard refresh in the browser (Ctrl+Shift+R) to load the new plugin.

Configuration¶

The plugin configuration is written in the profiles/web/cordis.patch.yml file. The following are explanations of the key configuration items:

- 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 的内部地址（留空则自动检测）

Note: jwtSecret is required only when ONLYOFFICE has JWT enabled.

Precautions¶

1. Environment Dependencies
   You need to run the DSH web profile, and dsh-better-sidebar must already be installed. A self-hosted ONLYOFFICE Document Server must be deployed (verified compatible with the 9.4 Community Edition).

2. Network and Permissions
   If document.url or callbackUrl uses private addresses, the Document Server must have the environment variable ALLOW_PRIVATE_IP_ADDRESS=true set in order to accept requests.

3. Security and Maintenance
   It is recommended to review the source code before installation to confirm the security logic. Because the plugin runs with the permissions of the current DSH process, ensure that the Document Server configuration meets the security requirements of your current network topology.

Conclusion¶

dsh-sidebar-onlyoffice provides DSH with a complete loop from “read-only preview” to “real-time editing.” Through the JWT security mechanism, same-origin proxy, and fine-grained AI interaction control, it makes it possible to directly work with office documents inside agent workflows. For more details, refer to the plugin directory or source repository.