dsh-office

一句话定位

为 DeepSeek Harness 提供 14 个 Office 文档工具，覆盖电子表格（.xlsx）、PDF、演示文稿（.pptx）、Word 文档（.docx）四种格式的生成、读取、编辑与公式质量审计，让 AI 能在对话中直接产出可交付的报告、合同、表格和幻灯片，而不是只能回 Markdown。

核心能力

• 生成与读取 .xlsx：支持公式单元格、表头加粗、列宽、数字格式；可分页（range_start/range_end、max_rows）读取大文件，公式文本原样保留
• 编辑 .xlsx：在已有工作簿上新增工作表、按单元格地址更新值或公式、追加行，并支持样式参数
• 公式质量门禁：用纯 TS 引擎重算所有公式并扫描 #REF!/#DIV/0!/#VALUE!/#N/A/#NAME?/#NUM! 等错误值；静态审计公式结构（数组公式陷阱、SUM 漏行、公式被硬编码覆盖、同列公式不一致、自引用、字面除零）
• 生成 PDF：内容块数组（标题/段落/表格/列表/代码块）输出真实 PDF，自动探测系统 CJK 字体并支持页脚页码
• 拆分/合并 PDF：按顺序合并多个 PDF；按 "1,3,5-7" 页码规则抽取指定页或每页拆成单文件
• 生成 .pptx：7 种版式（标题/章节/内容/双栏/图片/表格/图表），支持主题配色与演讲者备注
• 编辑 .pptx：在 <a:t> 节点上做 find/replace，保留版式与样式，适合改错字、改数字
• 读取 .pptx：提取幻灯片文本为 markdown，可选包含演讲者备注与结构信息（shape 名/位置、图片目标、表格行列）
• 生成 .docx：内容块数组生成 Word 文档，支持条纹表格、页面背景色、对角文字水印（适合"机密/DRAFT"草稿）
• 读取 .docx：从 Word 文档提取纯文本进上下文

技术实现

• 语言: TypeScript（ESM，tsc 编译到 lib/）
• 关键依赖: @deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-tools ^0.1.0-rc.5、@deepseek-ai/schemastery ^3.18.1；文档侧依赖 exceljs、pdfkit + pdf-parse + pdf-lib、pptxgenjs + jszip、docx + mammoth
• 架构模式: Cordis bundle 插件。src/index.ts 通过 apply(ctx, config) 读取 4 个工具族开关，按需调用 registerExcelTools / registerPdfTools / registerPptTools / registerDocxTools 4 个子模块；每个工具用 defineTool(...) 注册到 ctx.tools，由 cordis.patch.yml 的 - insert 在加载时挂入 profile
• 入口文件: src/index.ts（注册入口 + Config schema）；各工具实现分布在 excel.ts、pdf.ts、pdf-ops.ts、ppt.ts、docx.ts、excel-audit.ts、fonts.ts 中

适用场景

需要交付真实 Office 文件而不是 Markdown 的场景：用 AI 直接生成 Excel 数据报表（含公式并通过审计）、PDF 报告或合同（中文自动渲染）、PPT 演示稿（带主题/备注/编辑修订）、Word 文档（带水印/条纹表格）。也适合把已有 .xlsx/.pptx/.docx/.pdf 文件读回上下文做内容审查、按页范围抽取章节、合并拆分 PDF。纯文本能交付时不必启用本插件，体积更小也更好 diff。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:omdsh-dev/dsh-office

配置项

本插件提供一个 config.enable 开关，按工具族启用/关闭（默认全部启用；未列出的族保持启用，设为 false 即排除该族工具，常用于控制工具面大小）：

在 profile 的 cordis.patch.yml 中按需配置示例：

- insert:
    - id: dsh-office
      name: '@huiliyi37/dsh-office'
      config:
        enable:
          xlsx: false      # 不用电子表格工具
          pdf: true        # 保留 PDF 工具
          ppt: false       # 不用演示文稿
          docx: true       # 保留 Word 工具

常见问题

Q: 装上以后能用多少个工具？分别在哪些领域？

A: 默认装载全部 14 个工具，分为四族：xlsx（read/write/edit/recalc/audit）、pdf（create/read/merge/split）、ppt（create/read/edit）、docx（create/read）。如果不需要某个族，可以在 profile 的 cordis.patch.yml 里把对应开关设为 false，工具族会按需裁剪。

Q: 安装在旧版 dsh 上为什么会所有工具都报 "Cannot read properties of undefined (reading 'prepare')"？

A: 本插件要求 dsh ≥ 0.1.0-rc.5（对应 @deepseek-ai/dsh-tools ≥ 0.1.0-rc.5）。如果宿主核心的 dsh-tools 是 0.0.1 系列，npm 会重复装一份 dsh-tools，所有工具调用都会因工具工厂缺失 prepare 而崩溃。请升级宿主到 0.1.0-rc.5+ 再装即可。

Q: 生成的中文 PDF 出现方框或空白怎么办？

A: pdfkit 自带字体不含中文字形。本插件会按顺序探测 PingFang、微软雅黑、Noto Sans CJK 等系统字体并自动注册；找不到时会在返回内容里给出 ⚠ 警告，但不会自动装字体，请手动安装 Noto Sans CJK 或改用英文内容。

Q: 写完带公式的 .xlsx 之后还需要做什么？

A: 必须跑两次门禁才算完成：先跑 xlsx_recalc 让纯 TS 引擎重算并扫描 #REF!/#DIV/0!/#VALUE!/#N/A/#NAME?/#NUM! 等错误值，按 error_summary 位置修复直到 status: success；再跑 xlsx_audit 静态扫描公式结构（数组公式陷阱、SUM 漏行、公式被硬编码覆盖、同列公式不一致、自引用、字面除零），每条 warning 必须确认或修复，禁止批量放行。

Q: pptx_edit 改文本会破坏原版式吗？

A: 不会。该工具只替换 <a:t> 文本节点，不触碰布局、字体、配色与图形，适合改错字、改数字；批量替换可省略 slide 参数只改当前页或全部幻灯片；想保留原文件可指定 output_path 输出到新路径。

Q: pdf_merge 和 pdf_split 支持加密 PDF 吗？

A: 不支持。当前实现基于纯 JS 的 pdf-lib，加密/解密被有意省略（pdf-lib 尚未提供加密 API，引入系统 qpdf 会破坏零原生依赖）。如需处理加密 PDF 请先用其他工具解密后再传入。

Q: 大文件读取会被截断吗？怎么续读？

A: 会被截断并给出续读提示。xlsx_read 单次默认 200 行（最多 500），超过会在末尾返回 Continue with range_start: "A{n}" 提示；pdf_read 输出带 --- Page N --- 标记且 8000 字符截断，超长时返回 Continue with start_page: {n}。按提示分页调用即可，不要循环重试读完整个文件。

Q: 怎么卸载？

A: 执行 dsh plugin --profile <名称> remove @huiliyi37/dsh-office 即可。如果是通过手动方式把包放到 node_modules 并在 cordis.patch.yml 中 - insert 引用的，从 patch 文件里删掉 dsh-office 那条即可。

上手难度

入门 — 配置只有一个 4 字段的 enable 开关，开箱即用全部 14 个工具，按 README 的 JSON 示例直接调用即可生成第一个 .xlsx/.pdf/.pptx/.docx；唯一需要注意的是 xlsx 的"公式优先"纪律（先 recalc 再 audit 至全绿），其余工具无强制门禁。

已知问题与限制

• pdf_merge / pdf_split 不支持加密 PDF（src/pdf-ops.ts:4-7）：基于纯 JS pdf-lib 实现，未提供加密/解密 API，避免引入系统 qpdf 以保持零原生依赖；加密 PDF 需先用其他工具解密
• pdf_create 在找不到系统 CJK 字体时会输出中文方框（src/pdf.ts:68）：仅在返回内容里给出 ⚠ 警告，不自动安装字体；跨平台字体候选见 src/fonts.ts:24-37
• xlsx_recalc 是轻量纯 TS 引擎（src/excel-audit.ts:14-16）：不是完整 Excel 仿真，不支持的函数会被列为 warning 并按 #NAME? 求值；array_formula_risk 类型（"聚合(IF(区域))"）在 Excel 普通模式下仍可能返回 #VALUE!，建议改写为 MEDIAN(区域) / AVERAGEIF / AGGREGATE
• xlsx_audit 是启发式扫描（src/excel-audit.ts:14-16）：只标记疑似问题，不自动修复；交付前需逐条确认或修复
• pptx_read / pptx_edit 对 .pptx 体积有 100 MiB 硬上限（src/ppt.ts:32）：超大文件会直接抛 file too large 错
• 重复安装风险（README.md:30）：宿主核心若携带 0.0.1 系列 dsh-tools，本插件会重复装一份，导致所有工具调用因找不到 prepare 而崩溃，需升级宿主到 0.1.0-rc.5+

English | 中文

Office document tools for DeepSeek Harness (dsh): generate, read, and edit spreadsheets (.xlsx), PDFs, presentations (.pptx), and Word documents (.docx).

Ported from the office plugins of the Tianshu terminal coding agent (Apache-2.0 licensed upstream), adapted to the dsh cordis tool model.

Tools

Install & load

Compatibility: requires dsh ≥ 0.1.0-rc.5 (bundles @deepseek-ai/dsh-tools ≥ 0.1.0-rc.5). Installing on an older core whose dsh-tools is a 0.0.1 release installs a second dsh-tools copy and crashes every tool call with Cannot read properties of undefined (reading 'prepare').

Full load (all 14 tools)

dsh plugin --profile <name> add @huiliyi37/dsh-office
dsh --profile <name>

The first dsh plugin call initializes the profile (@deepseek-ai/dsh-base is its first bundle) and appends this package to the profile's bundles list. Launching the profile then registers all tools automatically.

Load only the families you need

Pass a config row in your profile's cordis.patch.yml to enable/disable per family. Omitted families stay enabled; set a family to false to exclude it (useful to keep the tool surface small):

# cordis.patch.yml
- insert:
    - id: dsh-office
      name: '@huiliyi37/dsh-office'
      config:
        enable:
          xlsx: false      # skip spreadsheet tools
          pdf: true        # keep PDF tools
          ppt: false       # skip presentations
          docx: true       # keep Word tools

Families: xlsx (read/write/edit/recalc/audit), pdf (create/read/merge/split), ppt (create/read/edit), docx (create/read).

Uninstall

dsh plugin --profile <name> remove @huiliyi37/dsh-office

Manual alternative

Install the package anywhere Node resolution can find it and reference it from your own cordis.patch.yml (same config.enable switches apply):

npm install @huiliyi37/dsh-office

# cordis.patch.yml
- insert:
    - id: dsh-office
      name: '@huiliyi37/dsh-office'

Skill

The package ships a usage skill (skills/SKILL.md, anthropics-compatible format) that teaches the model large-file pagination and generation discipline. Install it into a skill discovery root:

mkdir -p ~/.dsh/skills && cp -r node_modules/@huiliyi37/dsh-office/skills/dsh-office ~/.dsh/skills/

Usage examples

// xlsx_write — create a workbook
{ "file_path": "report.xlsx", "data": [["Name", "Score"], ["Alice", 92]], "header_bold": true }

// pdf_create — document with a heading, table and list
{
  "destination_path": "doc.pdf",
  "title": "Quarterly Report",
  "content": [
    { "type": "heading", "text": "Summary" },
    { "type": "table", "headers": ["Region", "Revenue"], "rows": [["APAC", "120"]] },
    { "type": "list", "items": ["Alpha", "Beta"] }
  ],
  "page_numbers": true
}

// pptx_create — a deck with a title slide and a bullet slide
{
  "destination_path": "deck.pptx",
  "slides": [
    { "type": "title", "title": "Roadmap 2026" },
    { "type": "content", "title": "Highlights", "items": ["Plugin runtime", "Office tools"] }
  ]
}

Development

npm install
npm run build   # tsc → lib/
npm test        # vitest: round-trip tests through the tool execute path

License

Apache License 2.0. Tool logic ported from the Tianshu office plugins (also Apache-2.0 licensed, copyright Tianshu contributors); see file headers for per-module provenance.