dsh-doc-toolkit

📖 使用指南

安装完成后，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 字体。

---