cnkids/dsh-office-toolkit

dsh-office-toolkit

让 DSH 智能体自己读写 Word / Excel
纯 JavaScript，不装 Office 也能跑。

安装 ·
快速上手 ·
工具 ·
文档 ·
常见问题 ·
贡献 ·
Releases

装上这个宿主插件，智能体就能直接读报告、写台账、改表格、套合同模板、转换旧格式 —— 不用再手动搬文件，也不会因为通用 read 读不了二进制而卡住。

特性

- 纯 JS，开箱可用 —— 不装 Office / LibreOffice 就能读写 .docx .xlsx .xls .csv，Windows 上同样零依赖。
- 读写改一条龙 —— 新建文档、新建工作簿、编辑已有工作簿（样式 / 合并 / 冻结 / 筛选 / 图片 / 图表）、{{变量}} 模板套打、跨格式转换。
- 7 个工具自动注册 —— 见工具；描述里前置了文件类型关键字，智能体一次就能选对。
- 大表直接算，不用先搬数据 —— office_query 在文件内做筛选 / 分组 / 求和 / 计数 / 去重 / 排序，几万行也只返回结论；不给条件时返回表结构画像。
- 公式与日期是真的 —— = 开头写公式，date:2026-09-09 写日期，日期回读不受时区影响。
- 排版格式可读 —— .docx 传 withFormatting: true 即返回每段的字体 / 字号 / 行距 / 首行缩进 / 对齐与页面页边距（含 basedOn 继承链、隐式默认样式与主题字体），并给出格式分布和偏离主流的段落，用于比对行文规则。见用法与参数。
- 默认安全 —— 写入经 DSH 沙箱围栏（含 realpath 校验），文本来源中和公式注入，解析全走线性扫描（无 ReDoS），不联网、不常驻后台、依赖树无安装脚本。见安全说明。
- npm audit 0 条 —— 依赖取舍见设计说明。
- 可选的更高保真 —— 装了 LibreOffice / Word / macOS textutil 时，旧格式转换自动升级。

工具

| 工具 | 作用 |
| --- | --- |
| office_read | 读取 .docx .doc .rtf .odt .xlsx .xls .xlsb .ods .csv .tsv（Excel 以 TSV 返回；Word 长文可 offset 分段续读、outline 取标题大纲；.docx 可选返回排版格式报告） |
| office_query | 在表格文件内计算：条件筛选、分组、求和/均值/计数/去重、排序、表结构画像 —— 只返回结论 |
| office_write_docx | 新建文档（html / markdown / text） |
| office_write_xlsx | 新建工作簿（多表、表头、公式、日期、样式） |
| office_edit_xlsx | 编辑已有工作簿（单元格 / 样式 / 合并 / 行列 / 冻结 / 筛选 / 图片 / 图表） |
| office_fill_docx_template | {{变量}} 模板填充（合同、通知、批量套打） |
| office_convert | 格式互转（Word 家族 / 表格家族内部、.xls 导出、.pdf 输出） |

每个工具的参数表见用法与参数。

安装

dsh plugin --profile web add dsh-office-toolkit

装完必须重启 dsh web（或重开桌面端）并新建会话才会加载。

其它安装方式（GitHub 直链 / 完全离线 / 本地源码）

| 场景 | 命令 |
| --- | --- |
| GitHub 直链（不经过 npm） | dsh plugin --profile web add https://github.com/cnkids/dsh-office-toolkit/releases/latest/download/dsh-office-toolkit.tgz |
| 完全离线 | 解压 dsh-office-toolkit-offline.zip 后 dsh plugin --profile web add link:C:/dsh-office-toolkit |
| 本地源码 | dsh plugin --profile web add link:/path/to/dsh-office-toolkit |

离线包内含完整 node_modules，全程零下载。目标机器需 Node ≥ 20 与 pnpm。

dsh --profile web --dump-config | grep -A1 dsh-office-toolkit   # 校验是否加载
dsh plugin --profile web remove dsh-office-toolkit              # 卸载

更新

dsh plugin --profile web update

装完重启 dsh web 并新建会话。确认版本：启动日志里的 [dsh-office-toolkit] vX.Y.Z …，或 profile 里那份 package.json 的 version。

link: 安装不需要 pnpm，源码目录 git pull 即最新；GitHub 直链的内容会随发版变化，更新时改用上面这条（或先 remove 再 add）。

快速上手

读取（Excel 可用 sheets / range 限定窗口）：

{ "path": "报告.docx" }
{ "path": "销售.xlsx", "sheets": ["明细"], "range": "A1:F100" }

新建文档与工作簿：

{ "path": "周报.docx", "markdown": "# 周报\n\n- 完成 A\n- 完成 B\n" }
{ "path": "台账.xlsx", "sheets": [
{ "name": "明细", "header": true, "columnWidths": [14, 10, 12],
"rows": [["产品", "数量", "金额"], ["键盘", 10, "=B2199"], ["鼠标", 20, "=B389"]] } ] }

编辑已有工作簿（按顺序执行 ops，可加图表）：

{ "path": "台账.xlsx", "ops": [
{ "op": "set_value", "sheet": "明细", "ref": "E1", "value": "合计", "style": { "bold": true } },
{ "op": "style_range", "sheet": "明细", "range": "A1:C1", "style": { "fill": "DDEBF7", "align": "center" } },
{ "op": "add_chart", "sheet": "明细", "chartType": "column", "title": "金额对比",
"categories": "A2:A3", "series": [{ "range": "C2:C3" }], "anchor": "G2" } ] }

模板套打（模板里写 {{合同编号}}，变量名支持中文）与格式转换：

{ "templatePath": "合同模板.docx", "outputPath": "合同-001.docx",
"data": { "合同编号": "HT-2026-001", "甲方": "某某公司", "金额": "12800" } }
{ "sourcePath": "旧表.xls", "outputPath": "新表.xlsx" }
{ "sourcePath": "报告.docx", "outputPath": "报告.pdf" }

全部操作、参数与限制见用法与参数。

让智能体优先使用本插件

DSH 的工具注册没有优先级设置，模型只依据每个工具的 description 选择；而内置 read / write / edit 只处理 UTF-8 文本，读 .docx 会直接返回 Error: binary file，也不会提示该换哪个工具。本插件已把「哪类文件必须用本工具」写在每个描述最前面。

想更保险，在用户级指令文件 ~/.dsh/AGENTS.md（对所有项目与会话生效）里加一句：Office 文件一律用 office_read / office_query / office_write_ / office_edit_xlsx / office_fill_docx_template / office_convert，不要用通用 read/write/edit；表格的统计与筛选先用 office_query，别为几行汇总临时写脚本。该文件热加载，保存即生效。

常见问题

装完没反应？ 必须重启 dsh web（或重开桌面端）并新建会话 —— 插件与工具列表只在启动时加载。

Windows 提示 'git' 不是内部或外部命令？ github: 形式要用 git；改用固定直链即可绕开，或 winget install --id Git.Git -e。

内网 / 无外网怎么装？ 用 -offline.zip，解压后 link: 安装，全程零下载。

离线包自带依赖吗？ 是。.offline.zip 内含完整 node_modules，且发布前会用 node test/offline-check.mjs 校验每个依赖都落在包内（不允许借用 profile 目录）、依赖树无安装脚本；解压后 link: 安装全程零下载。

更新后版本没变？ 跑 dsh plugin --profile web update；若用的是 GitHub 直链，先 dsh plugin --profile web remove dsh-office-toolkit 再 add。
怎么确认插件版本 / 更新生效了？ 插件启动时会往 DSH 日志打印一行 [dsh-office-toolkit] vX.Y.Z 已注册 7 个 Office 工具；也可以直接看 profile 里那份 package.json 的 version（dsh --profile web --dump-config 能看到 profile 目录）。报错信息里也会带插件版本，便于排查。

某份文件读不出来？ 插件已按真实内容判断格式：非标准 zip（条目名含反斜杠）、改过后缀的文件（.doc 里其实是 docx、.xlsx 里其实是 CSV 等）都会自动按实际格式读取并给出提示。若报 BAD_CONTAINER，错误信息会列出文件里的实际条目，便于判断它到底是什么。详见用法与参数。

几万行的表怎么统计？ 用 office_query，它在文件内算完只回结论，不需要把整张表读进上下文。例如按地区求和、按金额倒序取前 20、只看某段时间的数据，都是一次调用；先不带条件跑一次还能拿到每列的类型、空值、去重数与高频值（表结构画像）。跨文件 join、透视表、统计建模这类插件覆盖不了的，再照常写脚本。

几百页的 Word 怎么读？ 一次 office_read 只返回 maxChars（默认 90000 字符）那么长，返回里会写明总字符数和「继续读」该传的 offset，下一次带上它就从断点接着读，不必从头重来；也可以先传 outline: true 拿标题大纲（级别 / 字符偏移 / 标题），直接跳到某一章。

转 PDF 报错？ .pdf 输出依赖本机 LibreOffice 或 Microsoft Word，纯 JS 不提供 PDF 渲染；写出 .doc / .odt 同理。各格式保真度见平台支持。

智能体还是用了通用 read？ 见上一节，补一条用户级指令即可稳定命中。

文档

| 文档 | 内容 |
| --- | --- |
| 用法与参数 | 全部示例、office_edit_xlsx 操作速查、参数与限制 |
| 平台支持 | 各格式保真度、外部转换器探测、工作方式 |
| 安全说明 | 已修漏洞、边界与假设、残余风险、私密报告入口 |
| 设计说明 | 为什么不用正则解析、目录结构、依赖取舍 |
| 开发与发版 | 跑测试、覆盖率、SonarQube、npm 发布、发版流程 |
| 版本记录 | 完整变更历史 |

版本记录

| 版本 | 变更 |
| --- | --- |
| 0.3.27 | Word 长文档可分段读：offset 续读（不再每次从头开始）+ outline 标题大纲跳读；逐段拼回与全文逐字节一致 |
| 0.3.26 | 修 office_fill_docx_template 描述里的字面量占位符导致 DSH 提示词组装报 malformed prompt variable reference：面向模型的文本一律不再出现双花括号变量写法，并加测试门禁 |
| 0.3.25 | 新增 office_query：在表格文件内筛选 / 分组 / 求和 / 计数 / 去重 / 排序，几万行只回结论；不给条件时返回表结构画像。数值与日期按真实写法识别，算不了的需求（跨文件 join、透视、建模）照常写脚本 |
| 0.3.24 | 安装改用包名 dsh-office-toolkit（不再依赖直链），其它方式折叠收起 |
| 0.3.23 | 发布自动化:推 v tag 由 GitHub Actions 发布 npm 并上传 Release 附件 |
| 0.3.22 | 文档精简：更新说明只留结论与命令 |
| 0.3.21 | 文档：更新请用带版本号的直链（latest 直链可能被 pnpm 复用缓存） |
| 0.3.20 | 主文档部件按包关系解析（非规范路径也能读）；启动日志与报错带上插件版本 |
| 0.3.19 | 部件名大小写不同也能读（连同引用一起归一化）；mammoth 认不出时重打包重试、再不行用内置解析器兜底 |
| 0.3.18 | 修 0.3.17 回归：读取非标准文件时报 Cannot add property containerNote（宿主参数是冻结的）；改为不改写调用方参数 |
| 0.3.17 | 读取兼容性：非标准 zip（条目名含反斜杠）自动修正、按真实内容识别改过后缀的文件；修正默认样式解析 bug |
| 0.3.16 | .docx 可读出排版格式（字体 / 字号 / 行距 / 缩进 / 对齐 / 页边距），withFormatting: true |
| 0.3.15 | 依赖装不全时点名缺哪个包并给出修复命令；二进制输出自检；离线包完整性门禁 |
| 0.3.14 | 文档重组：README 收敛为入口，细节移入 docs/ |

更早版本见版本记录。

贡献

- 问题与建议走 GitHub Issues；安全问题请用私密漏洞报告，不要发在公开 Issue 里。
- 欢迎 PR：改完请跑 npm test，并保证 SonarQube 无新增问题（见开发与发版）。
- 提交信息格式：v : ；每次版本变更都要同步本文档与版本记录。

许可证

MIT