DSH Doc Toolkit

DSH Doc Toolkit 是一个为 DeepSeek Harness (DSH) 设计的文档读写插件，让 AI 助手能够直接读取和生成 PDF、Word (.docx)、Excel (.xlsx)、CSV 等常用办公文档。

---

✨ 功能特性

功能	支持格式	说明
📖 读取文档	PDF、DOCX、XLSX、CSV	提取文本内容（PDF 需含文本层，扫描件不支持 OCR）
✏️ 写入文档	DOCX、XLSX、CSV、PDF	从结构化数据生成文档；PDF 支持标题/段落/表格，中文自动嵌入字体
📄 大文件分页	XLSX、CSV	通过 limit 和 offset 参数控制返回行数，防止撑爆上下文
🈶 中文 PDF 导出	PDF	自动查找系统 CJK 字体（TTF/TTC）并子集化嵌入，文本可复制、可搜索
🧠 AI 友好	所有格式	解析结果直接返回纯文本/TSV，方便大模型理解
🧩 内置 Skill	所有格式	插件加载时自动注册 doc-toolkit-usage 技能，教 AI 何时及如何调用工具

---

🚀 快速安装

前置条件

• 已安装 DeepSeek Harness 桌面版
• Node.js v18+ 与 npm（仅安装/开发时需要，运行时由 DSH 提供）

方式一：从 GitHub 安装（推荐给普通用户）

仓库已提交编译产物（lib/），克隆或直接安装即可使用，无需本机编译：

dsh plugin --profile web add https://github.com/qingmumingyang/dsh-doc-toolkit

如果当前环境没有 dsh 命令行（纯桌面版安装），请使用方式三。

方式二：本地开发安装

# 1. 进入项目目录
cd dsh-doc-toolkit

# 2. 安装依赖
npm install

# 3. 编译 TypeScript（生成 lib/ 目录）
npm run build

# 4. 加载到 DSH web profile
dsh plugin --profile web add D:\path\to\dsh-doc-toolkit

方式三：桌面版手动安装（没有 dsh 命令行时）

桌面版安装目录下没有独立的 dsh 命令，可手动完成等价操作：

# 1. 先完成上面的 npm install + npm run build

# 2. 在 profile 的 node_modules 中建立插件链接（与 DSH 自带的 junction 机制一致）
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-doc-toolkit" -Target "D:\path\to\dsh-doc-toolkit"

# 3. 把插件加入 profile 的 bundles 列表
#    编辑 %USERPROFILE%\.dsh\profiles\web\package.json，在 dsh.profile.bundles 中追加：
#    "dsh-doc-toolkit"

# 4. 完全退出并重启 DSH 桌面版

加载成功后，插件日志会输出：

[dsh-doc-toolkit] 插件已加载！
[dsh-doc-toolkit] 已注册 skill: doc-toolkit-usage

注意：DSH 的插件清单（Plugin Inventory）界面是只读的，安装/卸载需通过命令或手动方式完成。修改 src/ 后重新执行 npm run build 并重启 DSH 即可生效。

---

📖 使用指南

安装完成后，AI 助手会自动获得两个新工具（Tools）：

1. read_document —— 读取文档

参数说明：

参数	类型	必填	说明
file_path	string	✅	文件绝对路径或相对工作区的路径
format	string	❌	pdf / docx / xlsx / csv / auto（默认 auto，根据扩展名识别）
offset	number	❌	起始行号，从 1 开始（仅对 XLSX/CSV 有效）
limit	number	❌	最大返回行数（仅对 XLSX/CSV 有效）

对话示例（自然语言）：

“帮我读取 D:\report.pdf 的内容” “读取 D:\data.xlsx 的前 50 行”

底层调用 JSON：

{
  "file_path": "D:/data.xlsx",
  "format": "xlsx",
  "limit": 50
}

返回示例：

{
  "content": "[Sheet: Sheet1]\n姓名\t年龄\t城市\n张三\t28\t北京\n李四\t32\t上海",
  "format": "xlsx",
  "total_lines": 3,
  "limit": 50,
  "truncated": false
}

PDF 还会返回 pages（页数）；DOCX 有转换警告时返回 warnings。total_lines 为文件总行数，truncated 为是否因 limit 截断——截断时继续增大 offset 翻页。

2. write_document —— 写入/生成文档

参数说明：

参数	类型	必填	说明
file_path	string	✅	文件保存路径（自动创建父目录）
format	string	✅	docx / xlsx / csv / pdf
content	object	✅	结构化内容（格式见下方）

各格式的 content 写法：

格式	content 结构	示例
DOCX	{ "title"?, "paragraphs": [...] } 或 { "content": "纯文本" }	{ "title": "年度总结", "paragraphs": ["业绩增长 20%"] }
XLSX	{ "rows": [[...]] } 或 { "data": [{...}] }，可选 "sheet_name"	{ "rows": [["姓名","年龄"],["张三",28]] }
CSV	{ "rows": [[...]] }、{ "data": [{...}] } 或 { "content": "纯文本" }	{ "rows": [["姓名","年龄"],["张三",28]] }
PDF	{ "title"?, "paragraphs": [...] } 或 { "content": "纯文本" }，可选 "rows": [[...]]（渲染为表格）	见下方示例

CSV 字段含逗号、引号或换行时自动按 RFC 4180 转义；XLSX 二维数组走 aoa_to_sheet，对象数组走 json_to_sheet（键作为表头）。

对话示例（自然语言）：

“帮我生成一份销售报告 DOCX，包含标题和三个段落，保存到 D:\sales.docx” “把这张表格导出为 CSV：[[姓名, 分数], [小明, 95], [小红, 88]]，保存到 D:\scores.csv” “生成一份 PDF 报告，标题『2025 年度销售报告』，三段正文，最后带一张销量表格”

底层调用 JSON（生成 PDF）：

{
  "file_path": "D:/report.pdf",
  "format": "pdf",
  "content": {
    "title": "2025 年度销售报告",
    "paragraphs": ["本年度业绩增长 20%。", "展望明年，目标增长 30%。"],
    "rows": [["产品", "销量"], ["A 系列", 1200], ["B 系列", 860]]
  }
}

返回示例：

成功写入 PDF 文件: D:/report.pdf（共 1 页，标题「2025 年度销售报告」，2 个段落，表格 3 行，内嵌字体 simhei（子集 45 字符））

PDF 导出说明

• 字体策略：纯 ASCII 内容使用标准 Helvetica 字体（文件极小，无字体嵌入）；含中文等内容时自动查找系统 CJK 字体并子集化嵌入（只嵌入用到的字形，示例报告仅几十 KB），输出 Type0 + Identity-H + ToUnicode 结构，文本可复制、可搜索。
• 字体查找顺序：环境变量 DSH_CJK_FONT（TTF/TTC，分号分隔多个）→ Windows（simhei.ttf、msyh.ttc、simsun.ttc 等）→ macOS（PingFang、Hiragino 等）→ Linux（Noto CJK、文泉驿等）。TTC 字体集合会自动挑选覆盖最好的子字体。
• 排版：A4 页面、自动换行与分页；表格首行作表头（浅灰底），跨页时自动重复表头。
• 限制：字体中缺失的字符（如 emoji）降级为 .notdef 不渲染，返回消息会注明缺失数量；仅支持 TrueType 轮廓（TTF/TTC），不支持 CFF/OTF 字体。

---

🧩 内置 Skill

插件加载时会自动把 skills/doc-toolkit-usage/SKILL.md 注册为运行时 Skill（无需手动复制文件），AI 助手将据此判断何时以及如何调用这两个工具。

如果你希望该 Skill 对所有 profile 生效，也可以手动把它复制到用户级技能目录：

Copy-Item -Recurse skills\doc-toolkit-usage "$env:USERPROFILE\.dsh\skills\"

---

📂 项目结构

dsh-doc-toolkit/
├── src/
│   ├── index.ts                  # 插件入口：注册工具 + 运行时注册 Skill
│   ├── tools/
│   │   ├── read.ts               # 读取 PDF/DOCX/XLSX/CSV 的实现
│   │   ├── write.ts              # 写入 DOCX/XLSX/CSV 的实现
│   │   └── pdf-write.ts          # 纯 JS PDF 生成器（零依赖：字体解析/子集化/排版/组装）
│   └── types/
│       ├── index.ts              # 工具参数与返回类型定义
│       └── plugin-context.ts     # 宿主 Context 最小结构声明
├── skills/
│   └── doc-toolkit-usage/
│       └── SKILL.md              # 内置技能，教 AI 如何使用工具
├── lib/                          # 编译产物（已提交，GitHub 安装免编译）
├── test-output/
│   ├── tests.mjs                 # node:test 测试套件（25 个用例）
│   └── sample-*.{pdf,docx,xlsx,csv}  # 测试样例文件
├── package.json                  # npm 配置，含 dsh.bundle 声明
├── tsconfig.json                 # TypeScript 编译配置
├── cordis.patch.yml              # DSH 插件补丁文件（bundle 插入行）
└── README.md                     # 项目介绍文档（本文件）

---

⚠️ 注意事项

1. PDF 扫描件不支持 OCR 本插件通过 pdf-parse 提取 PDF 的文本层。如果 PDF 是扫描图片（无文字层），读取结果为空。如需 OCR 支持，请结合其他 OCR 插件使用。

2. 大文件处理 XLSX 和 CSV 文件较大时，请使用 limit/offset 参数分页读取，避免返回内容超出上下文窗口大小。

3. 写入会覆盖已有文件 write_document 会直接覆盖同路径的已存在文件，请确认路径无误。

4. Windows 路径格式 支持正斜杠（D:/temp/file.pdf）和反斜杠（D:\temp\file.pdf），建议在 JSON 调用中使用正斜杠避免转义问题。

5. PDF 导出需要系统中文字体 生成含中文的 PDF 时依赖系统字体（Windows 通常自带 SimHei/微软雅黑，开箱即用）。无中文字体的精简环境可用 DSH_CJK_FONT 指定字体路径。

6. 版本兼容 插件的 peerDependencies 与桌面版内置版本匹配（@deepseek-ai/cordis 4.x、@deepseek-ai/dsh-tools 0.1.x-rc）。若桌面版升级后工具注册报错，请同步调整这两个版本范围。

---

🛠️ 开发与调试

修改代码后重新编译

npm run build
# 完全退出并重启 DSH 桌面版即可生效（无需重新 add）

运行测试

项目自带基于 test-output/ 样例文件的测试套件（node:test，25 个用例，覆盖 4 种格式的读写、PDF 分页与字体子集、CSV 转义与错误路径）：

npm install   # 首次
npm run build # 先编译
npm test

卸载插件

dsh plugin --profile web remove dsh-doc-toolkit

手动安装的卸载：删除 %USERPROFILE%\.dsh\profiles\node_modules\dsh-doc-toolkit 链接，并从 %USERPROFILE%\.dsh\profiles\web\package.json 的 dsh.profile.bundles 中移除 "dsh-doc-toolkit"。

常见问题

Q：工具注册失败 / 插件加载报错？ A：先确认 npm run build 成功（lib/ 目录存在）；再确认 cordis.patch.yml 中 name 与 package.json 的 name 一致；最后检查桌面版版本与 peerDependencies 范围是否匹配。

Q：读取 PDF 报错 "bad XRef entry"？ A：这是 pdf.js v1.10 与 Node Buffer 共享内存池的兼容问题（小文件更容易触发）。本插件已在读取时把 Buffer 拷贝为独立 Uint8Array 修复，无需处理。

Q：生成中文 PDF 时提示找不到字体？ A：设置环境变量 DSH_CJK_FONT 指向一个 TTF/TTC 文件（可用分号指定多个候选），例如：

$env:DSH_CJK_FONT = "C:\Windows\Fonts\msyh.ttc"

Q：Windows 路径中的反斜杠问题？ A：代码中使用了 node:path 处理路径，正斜杠/反斜杠均可，但 JSON 参数中建议使用正斜杠。

---

🤝 贡献与反馈

欢迎提交 Issue 和 Pull Request！

• 报告 Bug：请附上 DSH 版本、操作系统、错误日志
• 功能建议：请清晰描述使用场景和期望行为
• 代码贡献：请保持 TypeScript 严格模式，并通过 npm run build 与 npm test

---

📄 许可证

本项目采用 MIT License，可自由使用、修改和商用。

---

Happy Coding! 🚀