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, "=B2*199"], ["鼠标", 20, "=B3*89"]] } ] }

编辑已有工作簿（按顺序执行 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

dsh-office-toolkit

설치

README