rong-coder/dsh-office-tool

dsh-office-tool

License: MIT
TypeScript
Node

一个 DeepSeek Harness（dsh）插件，通过驱动 OfficeCLI 二进制文件，为 agent 提供完整的 Office 文档能力——创建、读取、查询和编辑 .docx / .xlsx / .pptx，并通过 dsh-better-sidebar 在 dsh Web 侧边栏中实现文档内预览。

所有内容都使用 OfficeCLI 内置的高保真 HTML 引擎渲染，因此 agent 和用户都可以看到文档（通过侧边栏预览），而不是从 DOM 中猜测——无需安装 Microsoft Office。

功能特性

- 9 个面向模型的工具（office_create / get / query / set / add / remove / view / batch + office_cli 透传），覆盖完整的 OfficeCLI 命令面（通过 office_cli 支持 move/swap/merge/dump/import/validate/raw/…）。
- 处处使用结构化 --json 信封——成功 {success, data} / 失败 {success:false, error:{code, suggestion}}，并将 OfficeCLI 的自愈错误码暴露给模型。
- 侧边栏预览：在 better-sidebar 中打开 .docx / .xlsx / .pptx 时，会通过 iframe 使用 OfficeCLI 的 HTML 引擎渲染（文件变化时自动重新加载）。一个专用的 「Office 预览」tab 会运行 officecli watch，在 agent 编辑时通过 SSE 实时刷新预览。
- 也可无头运行：这些工具可在任何 profile 中激活（无需 Web UI）；只有预览路由需要等待 Web 服务器。

前置条件

- 已安装 dsh 并有一个可用的 profile（预览需要 web profile）。
- OfficeCLI 二进制文件可用（officecli install，或任意 PATH 安装）。如果插件无法解析该二进制文件，会在加载时明确报错。
- 侧边栏预览需要：在同一 profile 中安装 dsh-better-sidebar。

安装

into your web profile (requires dsh-better-sidebar for the preview)
dsh plugin --profile web add dsh-better-sidebar
dsh plugin --profile web add dsh-office-tool

restart dsh web, then hard-refresh the browser (Cmd/Ctrl+Shift+R)

从本地检出安装：dsh plugin --profile web add ./dsh-office-tool，或从本仓库的克隆中构建/附加（prepare 脚本会在安装时构建 lib/）：

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 中覆盖行（patch 会替换某一行的整个配置）：

- id: office-tool
config:
command: 'C:\path\to\officecli.exe'   # 二进制文件名或绝对路径（环境变量 DSH_OFFICECLI 优先）
timeoutMs: 60000
maxOutputBytes: 16777216
- id: office-tool-preview
config:
preview:
allowOutsideWorkspace: false        # 允许渲染宿主 cwd 之外的绝对路径
watch:
enabled: true
idleSeconds: 300

command 接受在 PATH 中解析的裸名称，或绝对路径（Windows .exe）。$DSH_OFFICECLI 会覆盖默认值 'officecli'。

工具

| 工具 | 功能 |
|---|---|
| office_create(file, type?, force?) | 创建空白的 .docx / .xlsx / .pptx |
| office_get(file, path?, depth?) | 以 JSON 读取一个元素及其子元素（/slide[1]/shape[2]、/body/p[3]、/Sheet1/A1、/） |
| office_query(file, selector, limit?) | 类 CSS 查询（run:contains(TODO)、row[Salary>5000 and Region=EMEA]） |
| office_set(file, path, props, find?, replace?) | 修改元素属性（文本/字体/颜色/布局/公式） |
| office_add(file, parent, type, props?, after?/before?/index?/from?) | 添加元素（幻灯片/形状/段落/行/工作表/图表……）或克隆（--from） |
| office_remove(file, path, shift?) | 移除元素 |
| office_view(file, mode, page?, cols?, maxLines?) | 以文本形式输出 text/outline/annotated/stats/issues；html/screenshot 返回预览 URL |
| office_batch(file, commands[], bestEffort?) | 原子化多操作批处理（op/path/props） |
| office_cli(argv) | 其他所有操作的原始透传：merge、dump、import、validate、raw、raw-set、move、swap、refresh、help、load_skill |

OfficeCLI 的路径/选择器语法和错误码全程适用——详见 officecli --help 或 officecli help  。

侧边栏预览

客户端部分通过 ctx.betterSidebar 注册：

- 文件查看器（office:officecli，扩展名 docx/xlsx/pptx，priority: 100）：在由宿主 /office/preview 路由提供的 iframe 中打开文件，该路由使用 officecli view  html 渲染文件。刷新按钮和轻量级 mtime 探测使其在 agent 编辑时保持最新。与内置 docx/xlsx/pptx 查看器的冲突按优先级解决（100 胜出）。
- 「Office 预览」标签页：输入文档路径后，它会启动 officecli watch（由宿主管理，临时端口）并将实时预览嵌入 iframe；当标签页关闭或插件卸载时，watch 进程停止。

宿主路由（仅在 ctx.webServer 存在时注册——在无头模式下从不注册）：

- GET /office/preview?path=…&cwd=…&page=… — 渲染后的 HTML（probe=1 → {mtime}）。
- GET /office/watch?path=…&action=open|close|status — 用于实时标签页的 JSON {url, port}。

仓库布局

├── src/
│   ├── index.ts            # 宿主插件入口：OfficeService + 工具注册
│   ├── service.ts          # argv 构建、spawn、--json 信封解析
│   ├── errors.ts           # OfficeError + officecli 错误码映射
│   ├── config.ts           # 配置类型 + 默认值 + 加载时校验
│   ├── paths.ts            # 预览路径解析 + 工作区检查
│   ├── tools/              # office_create/get/query/set/add/remove/view/batch/cli
│   ├── preview/            # /office/preview 路由 + 监听进程管理器
│   └── client/             # 客户端打包：better-sidebar 文件查看器 + 实时标签页
├── tests/                  # 单元测试、路由 HTTP 测试和真实 officecli 集成测试
├── cordis.patch.yml        # dsh 打包清单（要插入的插件行）
├── tsdown.config.ts        # 单次构建，产出宿主 + 客户端打包
└── package.json            # dsh.bundle + dsh.client 清单

开发

pnpm install
pnpm run typecheck
pnpm test                # 单元测试 + 路由测试；没有 officecli 时集成测试自动跳过
pnpm run build           # lib/index.js（工具）+ lib/preview.js（预览宿主）+ lib/client.js（客户端打包）

当 @officecli/officecli devDependency 下载了其二进制文件后，集成测试会针对真实的 officecli 运行（create → add → get → view html）。

已知限制和待办工作

- 实时预览仅在 OfficeCLI 变更时更新：officecli watch 在 officecli 编辑文档时刷新；其他工具更改的文件不会自动推送（快照查看器的探测仍会重新加载它们）。
- view screenshot 需要无头浏览器（Chrome/Edge/Chromium/Firefox 或 Playwright）安装在宿主机上，与 OfficeCLI 本身一样。
- KaTeX CDN：带数学公式的渲染 HTML 从 d.officecli.ai 加载 KaTeX（jsdelivr 作为回退）；没有网络时，公式降级为等宽文本。不含公式的文档完全离线。
- Electron/桌面外壳：预览路由由宿主同源提供；支持 Web UI（浏览器）。如果应用的 CSP 阻止了实时标签页 iframe（http://127.0.0.1:），请通过宿主索引 tap 添加 frame-src，或将标签页切换到宿主代理路由。
- 工具文件路径相对于宿主 cwd 解析（即启动 dsh 的位置）。office_* 工具中的相对路径在此解析；侧边栏预览还会遵循 better-sidebar 的会话 cwd。