前言¶

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 交互控制，它使得在智能體工作流中直接操作辦公文檔成爲可能。更多細節可參考插件目錄或源碼倉庫。