前言¶

DSH 的理念是「一切皆插件」，插件是擴展 agent 能力的主要方式。對於需要在 dsh 中讓 agent 創建、讀取、查詢和編輯 .docx、.xlsx、.pptx 的任務，dsh-office-tool 提供了一條現成的工具鏈。

它是一個 DeepSeek Harness（DSH / dsh）插件，GitHub 倉庫爲 rong-coder/dsh-office-tool，許可證爲 MIT。它通過 OfficeCLI 二進制驅動 Office 文檔能力，並在 dsh web sidebar 中提供文檔預覽；預覽部分依賴 dsh-better-sidebar。

這是什麼¶

dsh-office-tool 爲 dsh agent 提供創建、讀取、查詢和編輯 .docx、.xlsx、.pptx 的完整 Office 文檔能力。

它的核心特點是：

• 使用 OfficeCLI 二進制執行 Office 文檔操作。
• 向模型暴露一組結構化工具。
• 在 dsh web sidebar 中提供文檔預覽。
• 無需 Microsoft Office，依賴 OfficeCLI 內置高保真 HTML 引擎渲染預覽。
• 可在無 Web UI 的 profile 中啓用工具，僅預覽路由依賴 Web server。

核心功能¶

Office 文檔操作¶

插件提供 9 個模型工具，覆蓋創建、讀取、查詢、修改、添加、刪除、查看、批量操作和原始命令透傳：

office_create(file, type?, force?)
office_get(file, path?, depth?)
office_query(file, selector, limit?)
office_set(file, path, props, find?, replace?)
office_add(file, parent, type, props?, after?/before?/index?/from?)
office_remove(file, path, shift?)
office_view(file, mode, page?, cols?, maxLines?)
office_batch(file, commands[], bestEffort?)
office_cli(argv)

這些工具的作用如下：

• office_create：創建空白文檔。
• office_get：讀取元素及子元素。
• office_query：按選擇器查詢。
• office_set：修改元素屬性。
• office_add：添加或克隆元素。
• office_remove：刪除元素。
• office_view：查看 text、outline、annotated、stats、issues、html、screenshot 等模式。
• office_batch：執行批量操作。
• office_cli：透傳 OfficeCLI 原始命令，例如：

merge
dump
import
validate
raw
raw-set
move
swap
refresh
help
load_skill

結構化響應¶

工具使用結構化 --json 響應。失敗時，會暴露 OfficeCLI 錯誤碼，便於模型或調用方繼續處理。

Web sidebar 預覽¶

預覽功能依賴同一 profile 中安裝的 dsh-better-sidebar。

啓用後，dsh web sidebar 中可以提供：

• docx / xlsx / pptx 文件查看器。
• 運行 officecli watch 的「Office 預覽」tab。

即時預覽只在 OfficeCLI 修改文檔時刷新；其他工具修改的文件不會自動推送。

無 Web UI 時也可用¶

dsh-office-tool 可在無 Web UI 的 profile 中啓用工具。

預覽路由只在 host 存在 ctx.webServer 時註冊；headless 下僅工具可用。

安裝與啓用¶

先確認安裝前提：

• 已安裝 dsh，並配置可用 profile。
• 啓用預覽需要 web profile。
• 需要 OfficeCLI 二進制。
• $DSH_OFFICECLI 可覆蓋默認 officecli。
• 預覽功能需要同一 profile 安裝 dsh-better-sidebar。

先安裝預覽依賴，再安裝本插件：

dsh plugin --profile web add dsh-better-sidebar
dsh plugin --profile web add dsh-office-tool

如果從本地倉庫安裝，先克隆並安裝依賴：

git clone https://github.com/rong-coder/dsh-office-tool.git
cd dsh-office-tool && pnpm install
dsh plugin --profile web add ./dsh-office-tool

配置¶

插件支持通過 profile 的 cordis.patch.yml 配置這些項：

command
timeoutMs
maxOutputBytes
preview.allowOutsideWorkspace
watch.enabled
watch.idleSeconds

配置示例：

- id: office-tool
  config:
    command: 'C:\path\to\officecli.exe'
    timeoutMs: 60000
    maxOutputBytes: 16777216
- id: office-tool-preview
  config:
    preview:
      allowOutsideWorkspace: false
    watch:
      enabled: true
      idleSeconds: 300

command 可以寫二進制名或絕對路徑；$DSH_OFFICECLI 會覆蓋默認 officecli。

典型用法¶

創建空白文檔：

office_create(file, type?, force?)

讀取元素及子元素：

office_get(file, path?, depth?)

按選擇器查詢：

office_query(file, selector, limit?)

修改元素屬性：

office_set(file, path, props, find?, replace?)

添加或克隆元素：

office_add(file, parent, type, props?, after?/before?/index?/from?)

刪除元素：

office_remove(file, path, shift?)

查看文檔內容：

office_view(file, mode, page?, cols?, maxLines?)

批量執行操作：

office_batch(file, commands[], bestEffort?)

透傳 OfficeCLI 原始命令：

office_cli(argv)

適用場景與注意¶

dsh-office-tool 適合這些場景：

• 希望 dsh agent 直接處理 .docx、.xlsx、.pptx。
• 希望在 dsh web sidebar 中預覽 Office 文檔。
• 希望在無 Web UI 的 profile 中調用 Office 文檔工具。
• 希望使用 OfficeCLI raw passthrough 命令處理更復雜的文檔操作。

安裝前需要注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。
• 工具中的相對文件路徑按 dsh 啓動時的 host cwd 解析。
• office_view 的 screenshot 模式需要 host 安裝 headless 瀏覽器。
• 含公式的 HTML 會從 CDN 加載 KaTeX；無網絡時公式退化爲等寬文本。
• dsh-better-sidebar 在 package.json 的 peerDependenciesMeta 中標記爲 optional。
• 預覽路由只在 host 存在 ctx.webServer 時註冊；headless 下僅工具可用。

結尾¶

dsh-office-tool 的價值在於：把 Office 文檔能力封裝成 dsh agent 可直接調用的工具，並保留 web sidebar 預覽入口。社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係；如需在目錄中查找，可按插件名 dsh-office-tool 搜索。可覈實的倉庫地址是：

https://github.com/rong-coder/dsh-office-tool