pqkisvery666/dsh-basic-office

dsh-basic-office

DSH 办公文件插件：让 DeepSeek Harness 的 Agent 阅读常见二进制文档（PDF / DOCX / XLSX / PPTX / CSV），并生成常见办公文件（DOCX / XLSX / PPTX / PDF / CSV）。

DSH 原生的 read / write / edit 只处理 UTF-8 文本（read_image 只处理图片），二进制办公文档是空白。本插件补齐这一块，且不与任何原生工具重名/冲突（全部使用 office_* 前缀）。

提供的工具

| 工具 | 说明 |
|---|---|
| office_read_pdf | 提取 PDF 文本，支持 page_start / page_end 页范围与 max_chars 截断 |
| office_read_docx | 提取 Word .docx 文本（标题、段落、表格文字） |
| office_read_xlsx | 读取 .xlsx / .xls / .csv，按工作表返回制表符分隔的行；支持 sheet / range / max_rows |
| office_read_pptx | 提取 PowerPoint .pptx 每页幻灯片的文字（含表格文字） |
| office_write_docx | 生成 Word 文档：居中标题、heading1-3/quote/普通段落（粗体/斜体/对齐/颜色）、带表头底色的表格 |
| office_write_xlsx | 生成 Excel 工作簿：多工作表、字符串/数字/布尔/空单元格、自动列宽 |
| office_write_pptx | 生成 PPT：16:9 宽屏、标题/副标题/分级项目符号/表格 |
| office_write_pdf | 生成 PDF：多页、标题/段落/项目符号/表格；中文等非 ASCII 文本自动使用 Windows 系统字体（微软雅黑等） |
| office_write_csv | 生成 CSV：可选表头、comma/tab/semicolon 分隔符、默认带 UTF-8 BOM（Excel 打开中文不乱码） |

设计要点（与原生能力对齐）

- 沙箱一致：生成文件与原生 write 一样受会话沙箱策略约束——workspace-write 下只能写入工作区与系统临时目录，越界会得到与原生相同的 [sandbox: ...] 拒绝提示，并支持 sandbox_permissions + justification 的一次性升级（需用户批准）。
- 读前保护：生成文件遵循原生 fs 观察策略（先读后覆写），未读过的已有文件不会被直接覆盖。
- 路径解析：相对路径按会话工作区解析，与原生 read / write 一致。
- 观察事件：读取/生成都会发出 fs/observed，与原生工具链互通。
- 规范化：工具定义遵循官方文档 docs/user/develop/basic/tool.md 与 docs/cookbook/adding-a-tool.md（defineTool + ctx.tools.register、参数 DSL、规范返回值、output.render、纯函数 presentCall）。

安装（用户）

无需 git，直接从 GitHub 下载安装（已实测可用）：
dsh plugin --profile web add https://codeload.github.com/pqkisvery666/dsh-basic-office/tar.gz/refs/heads/main

或机器上有 git 时：
dsh plugin --profile web add git+https://github.com/pqkisvery666/dsh-basic-office.git

安装后 重启 dsh web 服务（Ctrl+C 后重新 dsh web），新工具即对所有会话生效。

dsh plugin --profile web up      # 更新
dsh plugin --profile web remove dsh-basic-office   # 卸载

卸载

dsh plugin --profile web remove dsh-basic-office

在会话中使用

直接对模型说即可，例如：

- 「读一下 C:\path\报告.pdf 的前 10 页」
- 「把这个表格生成 data.xlsx 和 data.csv」
- 「把以下内容生成一份 周报.docx（带标题和表格）和一个 5 页的 汇报.pptx」
- 「把这段总结输出成 总结.pdf」

开发

pnpm install        # 安装依赖
node test/smoke.mjs # 冒烟测试：5 种格式生成↔解析回环 + 全工具面执行

目录结构

dsh-basic-office/
cordis.patch.yml   # dsh.bundle.patch 层：插入插件行（office-tools）
lib/index.js       # Cordis 插件入口：9 个工具的注册与执行
lib/parsers.js     # 解析侧纯函数（PDF/DOCX/XLSX/PPTX）
lib/generators.js  # 生成侧纯函数（DOCX/XLSX/PPTX/PDF/CSV）
test/smoke.mjs     # 冒烟测试

已知限制

- 扫描版 PDF（纯图片无文字层）无法提取文本（无 OCR）。
- 老式二进制 .doc / .xls 仅 .xls 受支持；.doc 请先另存为 .docx。
- 非 Windows 平台生成 PDF 时若无 CJK 系统字体，中文无法渲染（西文正常）。
- PPTX 读取不含图片/绘图中的文字。