🧾 dsh-word-docs

给 DeepSeek Harness 的办公 Word 文档插件——说一句话,出正式文档。

生成、编辑、读取、统计、转 PDF .docx,底层是纯 Python 标准库(只有 zipfile + xml.etree),零第三方依赖——不需要 pip install 任何东西,装完即用。中文字体(宋体/eastAsia)自动处理,正式公文排版一步到位。

---

真实生成效果(Quick Look 渲染):左=Markdown 会议纪要转公文版(页码+首行缩进+标题编号)· 中=劳动合同模板(页脚页码)· 右=周报(指定列宽表格+合并单元格+插入图片)

---

为什么用它

🚀 零依赖	纯标准库实现,装完即用;没有 python-docx / pandoc / LibreOffice 的依赖地狱
🇨🇳 中文优先	宋体正文、公文首行缩进 2 字符、"一、/（一）/1."式标题编号、A4 版式
📄 说人话出文档	对 AI 说"把这份 Markdown 转成 Word 加页码",它自己调工具完成
✏️ 不只是生成	能读、能改、能批量填模板、能转 PDF,覆盖文档全生命周期
🧩 Harness 原生	标准 dsh 插件:装进 profile 即注册 word_docs 工具 + word-docs 技能

快速开始(30 秒)

# 1. 安装
dsh plugin --profile web add git+https://github.com/Ei-Ayw/dsh-word-docs.git

# 2. 重启 dsh Web,然后直接对 AI 说:
#    "把这份 Markdown 转成 Word,加页码、首行缩进"
#    "生成一份劳动合同模板"
#    "读一下这个 docx 里写了什么,总结一下"
#    "把这个合同里的 {占位符} 批量填掉"

不想装?核心引擎是单文件,直接命令行用:

python3 scripts/worddocs.py md2docx --input demo/sample.md --output demo/meeting.docx \
    --page-number --first-line-indent --number-headings chinese

它能做什么(真实演示)

📄 生成:JSON 规格即文档

标题、正文(内联 加粗 / 斜体 / `代码`)、嵌套列表、表格(合并单元格 + 列宽)、图片、分页,一个 JSON 全搞定:

{
  "page": { "footer": { "pageNumber": true } },
  "headingNumbering": "chinese",
  "content": [
    { "type": "heading", "level": 0, "text": "2026 年第 35 周工作周报", "align": "center" },
    { "type": "paragraph", "text": "完成 **API 网关** 限流改造,压测 QPS 提升 40%" },
    { "type": "table", "colWidths": [3.5, 3, 3, 3],
      "headers": ["指标", "本周", "上周", "环比"],
      "rows": [ ["需求交付数", "5", "4", "+25%"],
                [{ "text": "合并列", "colSpan": 2 }, "3", "-57%"] ] },
    { "type": "image", "path": "chart.png", "widthCm": 10, "alt": "趋势图" }
  ]
}

周报:表格+图片+自动编号	劳动合同:页脚页码+条款缩进	会议纪要:Markdown 一键转公文版

🔄 Markdown → Word(一条命令)

python3 scripts/worddocs.py md2docx --input demo/sample.md --output demo/meeting.docx \
    --page-number --first-line-indent --number-headings chinese

支持 ATX 标题、管道表格、嵌套列表、代码块、引用、图片、链接;--number-headings chinese 自动变成"一、/（一）"编号。

✏️ 编辑现有文档(不丢格式)

[
  { "op": "replaceText", "find": "旧文案", "replace": "新文案", "all": true },
  { "op": "append", "blocks": [{ "type": "heading", "level": 1, "text": "新章节" }] },
  { "op": "delete", "index": 5, "count": 2 },
  { "op": "fill", "values": { "{姓名}": "张三", "{日期}": "2026-09-01" } },
  { "op": "setFormat", "find": "标题", "align": "center", "bold": true,
    "fontSize": 14, "color": "FF0000", "lineSpacing": 1.5 }
]

replaceText 跨加粗/斜体边界替换时保留周边格式(字符级格式映射);fill 一条指令批量填模板;setFormat 改字体/字号/颜色/对齐/行距。

📖 读取、统计、转 PDF

python3 scripts/worddocs.py extract --input demo/weekly.docx --format markdown   # 还原成 Markdown
python3 scripts/worddocs.py info    --input demo/weekly.docx                     # 段落/表格/图片统计
python3 scripts/worddocs.py pdf     --input demo/weekly.docx                     # 转 PDF(需 LibreOffice/pandoc)

演示文件

demo/ 目录有 3 份生成好的文档,clone 下来直接打开:

文件	内容
demo/meeting.docx	会议纪要公文版(页码+缩进+编号)
demo/contract.docx	劳动合同模板(页脚页码,条款首行缩进)
demo/weekly.docx	周报(列宽表格+合并单元格+图片)
demo/sample.md / spec-*.json	生成它们的源文件,可复现

安装

# 方式一:安装为 profile bundle(推荐)
dsh plugin --profile web add git+https://github.com/Ei-Ayw/dsh-word-docs.git

# 方式二:本地开发(--patch,不需要 pnpm)
# word-docs.patch.yml:
#   - insert:
#       - id: word-docs
#         name: '/绝对路径/dsh-word-docs/index.js'
# dsh --profile web --patch ./word-docs.patch.yml

本地 link: 安装需让插件解析到 peer 依赖:ln -s ~/.dsh/profiles/node_modules/@deepseek-ai node_modules/@deepseek-ai(npm 安装无需)。

测试

node --test        # 13 个端到端用例,覆盖生成/编辑/提取往返、页码、缩进、编号、合并单元格、格式保留替换

目录结构

dsh-word-docs/
├── index.js              # Cordis 插件:word_docs 工具 + word-docs 技能
├── cordis.patch.yml      # bundle 补丁层
├── scripts/worddocs.py   # 核心引擎(单文件,纯标准库)
├── skills/word-docs/SKILL.md
├── demo/                 # 示例文档与规格
├── docs/                 # README 素材(预览图)
└── tests/

已知限制

• 标题编号为静态编号(生成时写死),非 Word 自动编号域
• 图片支持 png/jpg/gif;页眉页脚在生成时设置;无脚注/目录域/水印

License

MIT © Ei-Ayw